tapimo 0.0.0 → 0.0.2

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

@@ -0,0 +1,566 @@
+import { type Context, Hono } from 'hono'
+import * as z from 'zod/mini'
+
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as Response from '../../internal/Response.js'
+import * as Schema from '../../internal/Schema.js'
+import type * as Store from '../../internal/Store.js'
+import * as VerifiedTokens from '../../internal/VerifiedTokens.js'
+import { schema as readSchema } from '../../apps/verified-tokens.js'
+import type * as App from '../App.js'
+
+/** Required `chainId` query: admin mutations always address a chain explicitly. */
+const ChainIdQuery = Schema.ChainId
+
+/** Zod schemas owned by the admin verified-tokens handler. */
+export namespace schema {
+  /** A curated verified TIP-20 token entry (shared with the public read API). */
+  export const Token = readSchema.Token
+
+  /** Verified-token write/input fields without the server-derived `id`. */
+  export const Input = readSchema.Input
+
+  /** Path parameters addressing a single verified token. */
+  export const Params = readSchema.Params
+
+  /** Schemas for the listVerifiedTokens operation. */
+  export namespace listVerifiedTokens {
+    /** Query parameters for the verified-token list. */
+    export const Query = z
+      .strictObject({ chainId: ChainIdQuery })
+      .check(z.describe('Query parameters for the verified-token list.'))
+
+    /** Response: the curated list and the current snapshot version. */
+    export const Response = Schema.describe(
+      z.object({
+        data: z.array(Token).check(z.describe('The curated verified list for the chain.')),
+        version: z
+          .nullable(z.string())
+          .check(z.describe('Current snapshot version, or null when the list is empty.')),
+      }),
+      'Curated verified tokens and the current snapshot version.',
+    )
+  }
+
+  /** Schemas for the createVerifiedToken operation. */
+  export namespace createVerifiedToken {
+    /** Request body for creating a verified token. */
+    export const Body = z
+      .extend(Input, {
+        chainId: Schema.ChainId,
+        logo: z.optional(
+          z
+            .string()
+            .check(z.describe('Inline SVG logo markup, uploaded to the asset store on create.')),
+        ),
+      })
+      .check(z.describe('Request body for creating a verified token.'))
+
+    /** Response after a successful create. */
+    export const Response = Schema.describe(
+      z.object({
+        data: Token,
+        version: z.string().check(z.describe('New snapshot version after the write.')),
+      }),
+      'Created verified token and the new snapshot version.',
+    )
+  }
+
+  /** Schemas for the patchVerifiedToken operation. */
+  export namespace patchVerifiedToken {
+    /** Query parameters for a verified-token patch. */
+    export const Query = z
+      .strictObject({ chainId: ChainIdQuery })
+      .check(z.describe('Query parameters for a verified-token patch.'))
+
+    /** Request body for partially updating a verified token. */
+    export const Body = z
+      .partial(z.omit(Input, { address: true }))
+      .check(z.describe('Request body for partially updating a verified token.'))
+
+    /** Response after a successful patch. */
+    export const Response = createVerifiedToken.Response
+  }
+
+  /** Schemas for the deleteVerifiedToken operation. */
+  export namespace deleteVerifiedToken {
+    /** Query parameters for a verified-token delete. */
+    export const Query = z
+      .strictObject({ chainId: ChainIdQuery })
+      .check(z.describe('Query parameters for a verified-token delete.'))
+
+    /** Response after a successful delete. */
+    export const Response = Schema.describe(
+      z.object({
+        version: z.string().check(z.describe('New snapshot version after the removal.')),
+      }),
+      'New snapshot version after a delete.',
+    )
+  }
+
+  /** Schemas for the uploadVerifiedTokenLogo operation. */
+  export namespace uploadVerifiedTokenLogo {
+    /** Query parameters for a logo upload. */
+    export const Query = z
+      .strictObject({ chainId: ChainIdQuery })
+      .check(z.describe('Query parameters for a logo upload.'))
+
+    /** Response after a successful logo upload. */
+    export const Response = Schema.describe(
+      z.object({
+        key: z.string().check(z.describe('Asset-store key the logo was written to.')),
+        path: z.string().check(z.describe('Public path of the logo under the main API origin.')),
+      }),
+      'Stored logo location.',
+    )
+  }
+
+  /** Schemas for the getVerifiedTokenLogo operation. */
+  export namespace getVerifiedTokenLogo {
+    /** Query parameters for a logo read. */
+    export const Query = z
+      .strictObject({ chainId: ChainIdQuery })
+      .check(z.describe('Query parameters for a logo read.'))
+  }
+
+  /** Schemas for the replaceVerifiedTokens operation. */
+  export namespace replaceVerifiedTokens {
+    /** Query parameters for a bulk replace. */
+    export const Query = z
+      .strictObject({ chainId: ChainIdQuery })
+      .check(z.describe('Query parameters for a bulk replace.'))
+
+    /** Request body for replacing a chain's entire verified list. */
+    export const Body = z
+      .object({
+        tokens: z.array(Input).check(z.describe('The full verified list to publish for the chain.')), // prettier-ignore
+      })
+      .check(z.describe('Request body for replacing a chain verified list.'))
+
+    /** Response after a successful bulk replace. */
+    export const Response = Schema.describe(
+      z.object({
+        data: z.array(Token).check(z.describe('The published verified list.')),
+        version: z.string().check(z.describe('New snapshot version after the replace.')),
+      }),
+      'Published verified list and the new snapshot version.',
+    )
+  }
+}
+
+/**
+ * Management routes for the curated verified-token list, backed by the request's
+ * `verifiedTokens` store; all `404` when no store is configured. Mutations accept
+ * an optional `If-Match` precondition (`412` on mismatch).
+ *
+ * - `POST /` creates a token (`409` on a duplicate address or symbol).
+ * - `PUT /` replaces a chain's entire list (seed/rollback).
+ * - `PATCH /:address` partially updates a token (`404` if absent).
+ * - `DELETE /:address` removes a token (`404` if absent).
+ * - `PUT /:address/logo` uploads a curated logo SVG (gated on `assets`).
+ */
+export function verifiedTokens() {
+  return new Hono<App.Environment>()
+    .get(
+      '/',
+      OpenApi.validate('query', schema.listVerifiedTokens.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'listVerifiedTokens',
+        responses: OpenApi.responses({
+          errors: { 404: featureDisabledDescription },
+          success: {
+            description: 'Curated verified tokens.',
+            schema: schema.listVerifiedTokens.Response,
+          },
+        }),
+        summary: 'List verified tokens',
+        tags: ['Verified Tokens'],
+      }),
+      async (c) => {
+        const store = c.get('verifiedTokens')?.store
+        if (!store) return notEnabled(c)
+        const { chainId } = c.req.valid('query')
+        const snapshot = await VerifiedTokens.read(store, chainId)
+        return c.json(
+          Response.validated(schema.listVerifiedTokens.Response, {
+            data: snapshot?.list ?? [],
+            version: snapshot?.version ?? null,
+          }),
+        )
+      },
+    )
+    .post(
+      '/',
+      OpenApi.validate('json', schema.createVerifiedToken.Body, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'createVerifiedToken',
+        responses: OpenApi.responses({
+          errors: {
+            404: featureDisabledDescription,
+            409: 'Duplicate address or symbol.',
+            413: 'Logo exceeds the size limit.',
+            415: 'Logo is not valid SVG.',
+          },
+          success: {
+            description: 'Created verified token.',
+            schema: schema.createVerifiedToken.Response,
+          },
+        }),
+        summary: 'Create verified token',
+        tags: ['Verified Tokens'],
+      }),
+      async (c) => {
+        const store = c.get('verifiedTokens')?.store
+        if (!store) return notEnabled(c)
+        const { logo, ...body } = c.req.valid('json')
+        try {
+          if (logo !== undefined) {
+            const assets = c.get('assets')
+            if (!assets?.put) return assetsNotEnabled(c)
+            const svg = encodeLogo(logo)
+            const duplicate = await findDuplicate(store, body)
+            if (duplicate) throw duplicate
+            await assets.put(logoKey(body.chainId, body.address), {
+              body: svg,
+              contentType: 'image/svg+xml',
+            })
+          }
+          const { snapshot, token } = await VerifiedTokens.create(store, body)
+          return c.json(
+            Response.validated(schema.createVerifiedToken.Response, {
+              data: token,
+              version: snapshot.version,
+            }),
+          )
+        } catch (cause) {
+          return mutationError(c, cause)
+        }
+      },
+    )
+    .put(
+      '/',
+      OpenApi.validate('query', schema.replaceVerifiedTokens.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.validate('json', schema.replaceVerifiedTokens.Body, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'replaceVerifiedTokens',
+        responses: OpenApi.responses({
+          errors: {
+            404: featureDisabledDescription,
+            409: 'Duplicate address or symbol.',
+            412: 'Version precondition failed.',
+          },
+          success: {
+            description: 'Published verified list.',
+            schema: schema.replaceVerifiedTokens.Response,
+          },
+        }),
+        summary: 'Replace verified tokens',
+        tags: ['Verified Tokens'],
+      }),
+      async (c) => {
+        const store = c.get('verifiedTokens')?.store
+        if (!store) return notEnabled(c)
+        const { chainId } = c.req.valid('query')
+        const { tokens } = c.req.valid('json')
+        try {
+          const { snapshot } = await VerifiedTokens.replace(store, chainId, tokens, {
+            ...ifMatch(c),
+          })
+          return c.json(
+            Response.validated(schema.replaceVerifiedTokens.Response, {
+              data: snapshot.list,
+              version: snapshot.version,
+            }),
+          )
+        } catch (cause) {
+          return mutationError(c, cause)
+        }
+      },
+    )
+    .patch(
+      '/:address',
+      OpenApi.validate('param', schema.Params, {
+        code: 'address_invalid',
+        message: 'Invalid token address',
+      }),
+      OpenApi.validate('query', schema.patchVerifiedToken.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.validate('json', schema.patchVerifiedToken.Body, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'patchVerifiedToken',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'Verified token not found (or feature disabled).',
+            409: 'Duplicate symbol.',
+            412: 'Version precondition failed.',
+          },
+          success: {
+            description: 'Updated verified token.',
+            schema: schema.patchVerifiedToken.Response,
+          },
+        }),
+        summary: 'Update verified token',
+        tags: ['Verified Tokens'],
+      }),
+      async (c) => {
+        const store = c.get('verifiedTokens')?.store
+        if (!store) return notEnabled(c)
+        const { address } = c.req.valid('param')
+        const { chainId } = c.req.valid('query')
+        const body = c.req.valid('json')
+        try {
+          const { snapshot, token } = await VerifiedTokens.patch(store, chainId, address, body, {
+            ...ifMatch(c),
+          })
+          return c.json(
+            Response.validated(schema.patchVerifiedToken.Response, {
+              data: token,
+              version: snapshot.version,
+            }),
+          )
+        } catch (cause) {
+          return mutationError(c, cause)
+        }
+      },
+    )
+    .delete(
+      '/:address',
+      OpenApi.validate('param', schema.Params, {
+        code: 'address_invalid',
+        message: 'Invalid token address',
+      }),
+      OpenApi.validate('query', schema.deleteVerifiedToken.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'deleteVerifiedToken',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'Verified token not found (or feature disabled).',
+            412: 'Version precondition failed.',
+          },
+          success: {
+            description: 'Removed; returns the new snapshot version.',
+            schema: schema.deleteVerifiedToken.Response,
+          },
+        }),
+        summary: 'Delete verified token',
+        tags: ['Verified Tokens'],
+      }),
+      async (c) => {
+        const store = c.get('verifiedTokens')?.store
+        if (!store) return notEnabled(c)
+        const { address } = c.req.valid('param')
+        const { chainId } = c.req.valid('query')
+        try {
+          const { snapshot } = await VerifiedTokens.remove(store, chainId, address, {
+            ...ifMatch(c),
+          })
+          return c.json(
+            Response.validated(schema.deleteVerifiedToken.Response, {
+              version: snapshot.version,
+            }),
+          )
+        } catch (cause) {
+          return mutationError(c, cause)
+        }
+      },
+    )
+    .get(
+      '/:address/logo',
+      OpenApi.validate('param', schema.Params, {
+        code: 'address_invalid',
+        message: 'Invalid token address',
+      }),
+      OpenApi.validate('query', schema.getVerifiedTokenLogo.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      async (c) => {
+        const assets = c.get('assets')
+        const { address } = c.req.valid('param')
+        const { chainId } = c.req.valid('query')
+        const logo = await assets?.get(logoKey(chainId, address))
+        if (!logo)
+          return Response.error(c, {
+            code: 'logo_not_found',
+            message: 'Logo not found.',
+            status: 404,
+          })
+        c.header('Content-Type', logo.contentType)
+        return c.body(logo.body)
+      },
+    )
+    .put(
+      '/:address/logo',
+      OpenApi.validate('param', schema.Params, {
+        code: 'address_invalid',
+        message: 'Invalid token address',
+      }),
+      OpenApi.validate('query', schema.uploadVerifiedTokenLogo.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'uploadVerifiedTokenLogo',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'Asset uploads are not enabled.',
+            413: 'Logo exceeds the size limit.',
+            415: 'Body is not `image/svg+xml`.',
+          },
+          success: {
+            description: 'Stored logo location.',
+            schema: schema.uploadVerifiedTokenLogo.Response,
+          },
+        }),
+        summary: 'Upload verified-token logo',
+        tags: ['Verified Tokens'],
+      }),
+      async (c) => {
+        const assets = c.get('assets')
+        if (!assets?.put) return assetsNotEnabled(c)
+        const { address } = c.req.valid('param')
+        const { chainId } = c.req.valid('query')
+        const contentType = c.req.header('content-type')?.split(';')[0]?.trim().toLowerCase()
+        if (contentType !== 'image/svg+xml')
+          return Response.error(c, {
+            code: 'unsupported_media_type',
+            message: 'Logo uploads must be `image/svg+xml`.',
+            status: 415,
+          })
+        const body = await c.req.arrayBuffer()
+        if (body.byteLength === 0)
+          return Response.error(c, {
+            code: 'body_invalid',
+            message: 'Logo body is empty.',
+            status: 400,
+          })
+        if (body.byteLength > maxLogoBytes)
+          return Response.error(c, {
+            code: 'payload_too_large',
+            message: `Logo exceeds the ${maxLogoBytes / 1024} KiB limit.`,
+            status: 413,
+          })
+        // Keyed as the main API's loader reads it (curated icon takes precedence).
+        const key = logoKey(chainId, address)
+        await assets.put(key, { body, contentType: 'image/svg+xml' })
+        return c.json(
+          Response.validated(schema.uploadVerifiedTokenLogo.Response, {
+            key,
+            path: `/assets/${key}`,
+          }),
+        )
+      },
+    )
+}
+
+/** Largest accepted logo upload (SVG icons are tiny; this is generous). */
+const maxLogoBytes = 256 * 1024
+
+/** OpenAPI description shared by write routes' 404 when the feature is disabled. */
+const featureDisabledDescription = 'Verified-token management is not enabled (or not found).'
+
+/** Asset-store key the main API's loader reads for a token's curated icon. */
+function logoKey(chainId: number, address: string): string {
+  return `${chainId}/icons/${address.toLowerCase()}`
+}
+
+// Thrown by `encodeLogo` for an invalid inline SVG; mapped to its status below.
+class LogoError extends Error {
+  constructor(
+    readonly status: 400 | 413 | 415,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+// Validates inline SVG markup and returns its bytes; throws `LogoError` when the
+// body is empty, not SVG, or over the size limit.
+function encodeLogo(logo: string): ArrayBuffer {
+  const trimmed = logo.trimStart()
+  if (trimmed.length === 0) throw new LogoError(400, 'body_invalid', 'Logo body is empty.')
+  if (!/^<(\?xml|svg)[\s/>]/i.test(trimmed))
+    throw new LogoError(415, 'unsupported_media_type', 'Logo must be SVG markup.')
+  const bytes = new TextEncoder().encode(logo)
+  if (bytes.byteLength > maxLogoBytes)
+    throw new LogoError(413, 'payload_too_large', `Logo exceeds the ${maxLogoBytes / 1024} KiB limit.`) // prettier-ignore
+  return bytes.buffer as ArrayBuffer
+}
+
+// Returns the duplicate-address/symbol error a create would throw, or undefined,
+// so the logo upload can be skipped before it overwrites an existing icon.
+async function findDuplicate(
+  store: Store.State,
+  token: { address: string; chainId: VerifiedTokens.ChainId; symbol: string },
+): Promise<Error | undefined> {
+  const snapshot = await VerifiedTokens.read(store, token.chainId)
+  if (!snapshot) return undefined
+  if (snapshot.byAddress.has(token.address.toLowerCase()))
+    return new VerifiedTokens.DuplicateAddressError({ address: token.address, chainId: token.chainId }) // prettier-ignore
+  if (snapshot.bySymbol.has(token.symbol.toLowerCase()))
+    return new VerifiedTokens.DuplicateSymbolError({ chainId: token.chainId, symbol: token.symbol })
+  return undefined
+}
+
+function assetsNotEnabled(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'assets_not_enabled',
+    message: 'Asset uploads are not enabled for this deployment.',
+    status: 404,
+  })
+}
+
+// Reads the optional `If-Match` precondition, stripping ETag-style quotes.
+function ifMatch(c: Context<App.Environment>): { ifMatch?: string } {
+  const header = c.req.header('If-Match')
+  if (!header) return {}
+  return { ifMatch: header.replace(/^"|"$/g, '') }
+}
+
+// Maps `VerifiedTokens` write failures to the API's JSON error envelope.
+function mutationError(c: Context<App.Environment>, cause: unknown) {
+  if (cause instanceof LogoError)
+    return Response.error(c, { code: cause.code, message: cause.message, status: cause.status })
+  if (cause instanceof VerifiedTokens.DuplicateAddressError)
+    return Response.error(c, { code: 'duplicate_address', message: cause.message, status: 409 })
+  if (cause instanceof VerifiedTokens.DuplicateSymbolError)
+    return Response.error(c, { code: 'duplicate_symbol', message: cause.message, status: 409 })
+  if (cause instanceof VerifiedTokens.NotFoundError)
+    return Response.error(c, {
+      code: 'verified_token_not_found',
+      message: 'Verified token not found',
+      status: 404,
+    })
+  if (cause instanceof VerifiedTokens.VersionMismatchError)
+    return Response.error(c, { code: 'version_mismatch', message: cause.message, status: 412 })
+  return Response.upstream(c, cause)
+}
+
+function notEnabled(c: Context<App.Environment>) {
+  return Response.error(c, {
+    code: 'verified_tokens_not_enabled',
+    message: 'Verified-token management is not enabled for this deployment.',
+    status: 404,
+  })
+}

package/src/admin/index.ts

@@ -0,0 +1,2 @@
+export * as Access from './Access.js'
+export * as App from './App.js'