@polygonlabs/staker-pool-allocations-schemas 0.1.0

package/src/routes-management/distributions.ts

@@ -0,0 +1,87 @@
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { ErrorResponseSchema } from '@polygonlabs/openapi-registry/error-schemas';
+
+import { NetworkSchema, DistributionIdSchema } from '../common.ts';
+import {
+  DistributionDeleteResponseSchema,
+  DistributionTriggerRequestSchema,
+  DistributionTriggerResponseSchema
+} from '../management.ts';
+import { z } from '../zod.ts';
+
+// Management distribution routes. Both carry `security: [{ ApiKeyAuth: [] }]`
+// — the registry-driven router runs the ApiKeyAuth handler before request
+// validation, so an unauthenticated request 401s without parsing the body.
+// 400 (validation), 401 (auth), and 500 are auto-injected by TypedRegistry
+// from the declared request/security shape; only the handler-emitted codes
+// (404, 409) are declared explicitly here.
+export const addManagementDistributionRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'triggerDistribution',
+      method: 'post',
+      path: '/v1/{network}/management/distributions',
+      summary: 'Trigger a new distribution run',
+      description:
+        'Kicks off the in-process worker against the specified PoS block range. ' +
+        "Async — returns 202 with the row's current status and the worker runs " +
+        'out-of-band on the same pod. Operators poll the public distributions ' +
+        'endpoint (or the management :id view, Phase 1 follow-up) for terminal ' +
+        'state.\n\n' +
+        'Requires `x-api-key` header. Idempotent on `distributionId` when supplied. ' +
+        'Set `force: true` to re-run a completed/failed distribution covering the ' +
+        'same range — the prior row + allocations are hard-deleted before the ' +
+        'worker enqueues a new run.',
+      security: [{ ApiKeyAuth: [] }],
+      request: {
+        params: z.object({ network: NetworkSchema }),
+        body: {
+          content: { 'application/json': { schema: DistributionTriggerRequestSchema } }
+        }
+      },
+      responses: {
+        202: {
+          description: 'Trigger accepted. Status reflects the row at the moment of acceptance.',
+          content: { 'application/json': { schema: DistributionTriggerResponseSchema } }
+        },
+        409: {
+          description: '`force: true` on a non-terminal distribution.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'deleteDistribution',
+      method: 'delete',
+      path: '/v1/{network}/management/distributions/{distributionId}',
+      summary: 'Remove a stale distribution',
+      description:
+        'Requires `x-api-key`. Hard-deletes a `pending` / `running` / `failed` distribution ' +
+        'and its allocations — recovery for an orphaned run (e.g. a worker OOM-killed mid-run ' +
+        'leaves the row stuck at `running`). Refuses `completed` distributions (409): those are ' +
+        'published merkle roots claimers depend on — replace one via a force re-run instead.',
+      security: [{ ApiKeyAuth: [] }],
+      request: {
+        params: z.object({ network: NetworkSchema, distributionId: DistributionIdSchema })
+      },
+      responses: {
+        200: {
+          description: 'The distribution and its allocations were removed.',
+          content: { 'application/json': { schema: DistributionDeleteResponseSchema } }
+        },
+        404: {
+          description: 'No distribution with that (network, id).',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        },
+        409: {
+          description: 'The distribution is `completed` and cannot be deleted.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    });

package/src/routes-management/excluded-addresses.ts

@@ -0,0 +1,103 @@
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { AddressSchema, NetworkSchema } from '../common.ts';
+import {
+  AddExcludedAddressRequestSchema,
+  ManagedExcludedAddressSchema,
+  RemoveExcludedAddressResponseSchema
+} from '../management.ts';
+import { z } from '../zod.ts';
+
+// Response-side variants of the excluded-address schemas.
+//
+// The registry-driven router re-encodes every response via `z.encode`
+// against the declared schema, and `z.encode` rejects unidirectional
+// `.transform()`s ("Encountered unidirectional transform during encode").
+// `AddressSchema` lowercases via a one-way transform, so the shared
+// response schemas that embed it can't sit in a response slot. These
+// variants swap the address field for a plain lowercase-only validator —
+// handlers always emit the normalised form, so the constraint tightens
+// nothing on the wire. Same OpenAPI component names as the originals, so
+// the served spec is unchanged. Request-side use of `AddressSchema`
+// (body, path params) is unaffected: request validation decodes forward.
+const AddressOutputSchema = z
+  .string()
+  .regex(/^0x[0-9a-f]{40}$/)
+  .openapi({ example: '0xabc0000000000000000000000000000000000001' });
+
+const ManagedExcludedAddressOutputSchema = ManagedExcludedAddressSchema.extend({
+  address: AddressOutputSchema
+}).openapi('ManagedExcludedAddress');
+
+const ExcludedAddressListOutputSchema = z
+  .object({
+    items: z.array(ManagedExcludedAddressOutputSchema)
+  })
+  .openapi('ExcludedAddressListResponse');
+
+const RemoveExcludedAddressOutputSchema = RemoveExcludedAddressResponseSchema.extend({
+  address: AddressOutputSchema
+}).openapi('RemoveExcludedAddressResponse');
+
+// Excluded-address CRUD. All three carry `security: [{ ApiKeyAuth: [] }]`;
+// 400/401/500 are auto-injected by TypedRegistry from the declared
+// request/security shape.
+export const addExcludedAddressRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'listExcludedAddresses',
+      method: 'get',
+      path: '/v1/{network}/management/excluded-addresses',
+      summary: 'List addresses excluded from the merkle tree (settled off-chain)',
+      description:
+        'Requires `x-api-key`. Returns the curated excluded-address list for the network.',
+      security: [{ ApiKeyAuth: [] }],
+      request: { params: z.object({ network: NetworkSchema }) },
+      responses: {
+        200: {
+          description: 'The excluded-address list.',
+          content: { 'application/json': { schema: ExcludedAddressListOutputSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'addExcludedAddress',
+      method: 'post',
+      path: '/v1/{network}/management/excluded-addresses',
+      summary: 'Add (or re-label) an excluded address',
+      description:
+        'Requires `x-api-key`. Upserts on (network, address) — re-POSTing an existing ' +
+        'address updates its label. Takes effect on the next distribution run.',
+      security: [{ ApiKeyAuth: [] }],
+      request: {
+        params: z.object({ network: NetworkSchema }),
+        body: { content: { 'application/json': { schema: AddExcludedAddressRequestSchema } } }
+      },
+      responses: {
+        200: {
+          description: 'The upserted excluded-address row.',
+          content: { 'application/json': { schema: ManagedExcludedAddressOutputSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'removeExcludedAddress',
+      method: 'delete',
+      path: '/v1/{network}/management/excluded-addresses/{address}',
+      summary: 'Remove an excluded address',
+      description:
+        'Requires `x-api-key`. Idempotent — `removed: false` when the address was not present.',
+      security: [{ ApiKeyAuth: [] }],
+      request: { params: z.object({ network: NetworkSchema, address: AddressSchema }) },
+      responses: {
+        200: {
+          description: 'Removal result.',
+          content: { 'application/json': { schema: RemoveExcludedAddressOutputSchema } }
+        }
+      }
+    });

package/src/routes-management/operational.ts

@@ -0,0 +1,60 @@
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { z } from '../zod.ts';
+
+// /health-check is the K8s liveness probe — answers as long as the process
+// can serve HTTP at all. Registered at root (no /v1 prefix) because dry-dock
+// pod specs declare the probe path as `/health-check`, not `/v1/...`.
+//
+// /readiness is the degraded-mode signal — distinguishes "fully ready" from
+// "partially degraded but still serving" once dependencies are wired (DB +
+// subgraphs). Still a 200 stub; path matches the lst-api precedent.
+//
+// Neither carries `security` — pod probes are unauthenticated by design.
+export const OperationalStatusResponseSchema = z
+  .object({ status: z.literal('ok') })
+  .openapi('OperationalStatusResponse');
+
+export type OperationalStatusResponse = z.infer<typeof OperationalStatusResponseSchema>;
+
+// Generic over the parent's `Ops` and `Schemes` so the helper preserves
+// everything the caller had already registered; the chained `registerPath`
+// returns carry the cumulative narrow back through `.with(...)`.
+export const addOperationalRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'getHealthCheck',
+      method: 'get',
+      path: '/health-check',
+      summary: 'Liveness probe',
+      description:
+        'K8s liveness probe — answers as long as the process can serve HTTP. ' +
+        'Unauthenticated; dry-dock pod specs hit this exact root path.',
+      responses: {
+        200: {
+          description: 'Service is alive.',
+          content: { 'application/json': { schema: OperationalStatusResponseSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'getReadiness',
+      method: 'get',
+      path: '/readiness',
+      summary: 'Readiness probe',
+      description:
+        'Degraded-mode signal — distinguishes "fully ready" from "partially ' +
+        'degraded but still serving". Currently a 200 stub; the real DB + ' +
+        'subgraph reachability probe is outstanding work. Unauthenticated.',
+      responses: {
+        200: {
+          description: 'Service is ready.',
+          content: { 'application/json': { schema: OperationalStatusResponseSchema } }
+        }
+      }
+    });

package/src/routes-public/addresses.ts

@@ -0,0 +1,58 @@
+// Per-address read routes spanning all completed distributions on one
+// network: the cross-distribution allocation history (with live claim
+// status) and the batched unclaimed-proofs payload.
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { AddressSchema, NetworkSchema } from '../common.ts';
+import { UnclaimedProofsResponseSchema } from '../unclaimed-proofs.ts';
+import { z } from '../zod.ts';
+import { AllocationHistoryResponseWireSchema } from './wire.ts';
+
+export const addAddressRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'getAddressAllocationHistory',
+      method: 'get',
+      path: '/v1/{network}/addresses/{address}/allocations',
+      summary: 'Per-address cross-distribution allocation history with live claim status',
+      description:
+        'Returns every allocation row for the given address across all completed ' +
+        'distributions on the network, enriched with `status: "claimed" | "unclaimed"` ' +
+        'derived live at request time by querying the pos-staker-pool-claims subgraph ' +
+        '(spec §3.6, D10). Empty array if the address never qualified.',
+      request: {
+        params: z.object({ network: NetworkSchema, address: AddressSchema })
+      },
+      responses: {
+        200: {
+          description: 'History rows ordered most-recently-completed first.',
+          content: { 'application/json': { schema: AllocationHistoryResponseWireSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'getUnclaimedProofs',
+      method: 'get',
+      path: '/v1/{network}/addresses/{address}/unclaimed-proofs',
+      summary: 'Per-address unclaimed-proofs array — the primary claim-flow UI endpoint',
+      description:
+        "Returns the address's outstanding allocations with merkle proofs ready to " +
+        'submit to the claimer contract in one batched transaction. Proof generation is ' +
+        'on demand from the persisted leaves (spec D9); the in-memory tree cache absorbs ' +
+        'repeat calls for the same distribution. Empty array if every allocation has been ' +
+        'claimed (or the address has none).',
+      request: {
+        params: z.object({ network: NetworkSchema, address: AddressSchema })
+      },
+      responses: {
+        200: {
+          description: 'Batch of unclaimed-proof entries ordered oldest-distribution first.',
+          content: { 'application/json': { schema: UnclaimedProofsResponseSchema } }
+        }
+      }
+    });

package/src/routes-public/allocations.ts

@@ -0,0 +1,104 @@
+// Allocation read routes scoped to a single distribution: the paginated
+// claimable (in-tree) list, the off-chain (merkle-excluded) settlement
+// list, and the single-address lookup.
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { ErrorResponseSchema } from '@polygonlabs/openapi-registry/error-schemas';
+
+import {
+  AddressSchema,
+  DistributionIdSchema,
+  NetworkSchema,
+  PaginationQuerySchema
+} from '../common.ts';
+import { z } from '../zod.ts';
+import {
+  AllocationListResponseWireSchema,
+  AllocationRowWireSchema,
+  ExcludedAllocationsResponseWireSchema
+} from './wire.ts';
+
+export const addAllocationRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'listAllocations',
+      method: 'get',
+      path: '/v1/{network}/distributions/{distributionId}/allocations',
+      summary: 'List allocations for a completed distribution',
+      description: 'Paginated by `leafIndex` ascending.',
+      request: {
+        params: z.object({ network: NetworkSchema, distributionId: DistributionIdSchema }),
+        query: PaginationQuerySchema
+      },
+      responses: {
+        200: {
+          description: 'Page of allocation rows.',
+          content: { 'application/json': { schema: AllocationListResponseWireSchema } }
+        },
+        // Same 400 override rationale as `listDistributions`: the opaque
+        // cursor decodes in the handler and 400s with `info.code:
+        // 'INVALID_CURSOR'`, which the auto-injected ValidationErrorResponse
+        // shape would strip.
+        400: {
+          description:
+            'Invalid pagination cursor (`info.code: "INVALID_CURSOR"`) or ' +
+            'request failed schema validation.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        },
+        404: {
+          description: 'Distribution not found or not yet completed.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'listExcludedAllocations',
+      method: 'get',
+      path: '/v1/{network}/distributions/{distributionId}/excluded-allocations',
+      summary: 'List off-chain (merkle-excluded) allocations for a distribution',
+      description:
+        'Recipients allocated but excluded from the merkle tree (excluded addresses) — ' +
+        'not claimable on-chain, settled manually. Not paginated (small bounded set). ' +
+        '`totalAmount` equals the distribution `total_allocated - claimable_total`.',
+      request: {
+        params: z.object({ network: NetworkSchema, distributionId: DistributionIdSchema })
+      },
+      responses: {
+        200: {
+          description: 'The off-chain allocation set.',
+          content: { 'application/json': { schema: ExcludedAllocationsResponseWireSchema } }
+        },
+        404: {
+          description: 'Distribution not found or not yet completed.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'getAllocation',
+      method: 'get',
+      path: '/v1/{network}/distributions/{distributionId}/allocations/{address}',
+      summary: 'Get a single address allocation in a distribution',
+      request: {
+        params: z.object({
+          network: NetworkSchema,
+          distributionId: DistributionIdSchema,
+          address: AddressSchema
+        })
+      },
+      responses: {
+        200: {
+          description: 'Allocation row.',
+          content: { 'application/json': { schema: AllocationRowWireSchema } }
+        },
+        404: {
+          description: 'Distribution or allocation not found.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    });

package/src/routes-public/distributions.ts

@@ -0,0 +1,69 @@
+// Distribution read routes: paginated list + single-distribution detail.
+// Only completed runs are surfaced on the public API; pending/running/
+// failed rows 404 (the completed-only filter lives in the db package).
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { ErrorResponseSchema } from '@polygonlabs/openapi-registry/error-schemas';
+
+import { DistributionIdSchema, NetworkSchema, PaginationQuerySchema } from '../common.ts';
+import { DistributionDetailSchema, DistributionListResponseSchema } from '../distribution.ts';
+import { z } from '../zod.ts';
+
+export const addDistributionRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'listDistributions',
+      method: 'get',
+      path: '/v1/{network}/distributions',
+      summary: 'List completed distributions',
+      description:
+        'Paginated list of completed distributions, oldest first by id (e.g. `2026-04`). ' +
+        'Non-completed rows are not surfaced on the public API.',
+      request: {
+        params: z.object({ network: NetworkSchema }),
+        query: PaginationQuerySchema
+      },
+      responses: {
+        200: {
+          description: 'Page of distribution summaries.',
+          content: { 'application/json': { schema: DistributionListResponseSchema } }
+        },
+        // Override the auto-injected ValidationErrorResponse 400: this route
+        // also emits a handler-thrown `BadRequest` for an undecodable opaque
+        // cursor, whose `info` is `{ code: 'INVALID_CURSOR' }` rather than
+        // section-keyed validation trees. The generic ErrorResponse shape is
+        // the honest superset of both bodies — encoding the cursor body
+        // against the narrower ValidationErrorResponse would silently strip
+        // `info.code`.
+        400: {
+          description:
+            'Invalid pagination cursor (`info.code: "INVALID_CURSOR"`) or ' +
+            'request failed schema validation.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'getDistribution',
+      method: 'get',
+      path: '/v1/{network}/distributions/{distributionId}',
+      summary: 'Get a single completed distribution',
+      request: {
+        params: z.object({ network: NetworkSchema, distributionId: DistributionIdSchema })
+      },
+      responses: {
+        200: {
+          description: 'Distribution detail.',
+          content: { 'application/json': { schema: DistributionDetailSchema } }
+        },
+        404: {
+          description: 'Distribution not found or not yet completed.',
+          content: { 'application/json': { schema: ErrorResponseSchema } }
+        }
+      }
+    });

package/src/routes-public/operational.ts

@@ -0,0 +1,55 @@
+// Operational routes for the public REST API.
+//
+// /health-check is the K8s liveness probe — answers as long as the process
+// can serve HTTP at all. Registered at root (no /v1 prefix) because
+// dry-dock pod specs declare the probe path as `/health-check`, not
+// `/v1/...`. /readiness is the degraded-mode signal; still a 200 stub
+// pending the real DB + subgraph reachability probe. Both paths and their
+// `{"status":"ok"}` bodies are load-bearing for dry-dock probes — never
+// rename or version them.
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { z } from '../zod.ts';
+
+// Exported (and aliased to its registered name in the package barrel) so
+// the @polygonlabs/zod-to-openapi-heyapi codegen audit can resolve it.
+export const OperationalStatusSchema = z
+  .object({ status: z.literal('ok') })
+  .openapi('OperationalStatus');
+
+// Generic over the parent's `Ops` and `Schemes` accumulators so the helper
+// preserves everything registered before `.with(addOperationalRoutes)`.
+export const addOperationalRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r
+    .registerPath({
+      operationId: 'getHealthCheck',
+      method: 'get',
+      path: '/health-check',
+      summary: 'Liveness check (K8s probe)',
+      responses: {
+        200: {
+          description: 'Service is alive.',
+          content: { 'application/json': { schema: OperationalStatusSchema } }
+        }
+      }
+    })
+    .registerPath({
+      operationId: 'getReadiness',
+      method: 'get',
+      path: '/readiness',
+      summary: 'Readiness check',
+      description:
+        'Distinguishes "fully ready" from "partially degraded but still serving". ' +
+        'Currently a 200 stub — the real DB + subgraph reachability probe is outstanding work.',
+      responses: {
+        200: {
+          description: 'Service is ready.',
+          content: { 'application/json': { schema: OperationalStatusSchema } }
+        }
+      }
+    });

package/src/routes-public/proofs.ts

@@ -0,0 +1,46 @@
+// Single-allocation merkle-proof route.
+import type { RouteWithOpId, TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { ErrorResponseSchema } from '@polygonlabs/openapi-registry/error-schemas';
+
+import { AddressSchema, DistributionIdSchema, NetworkSchema } from '../common.ts';
+import { z } from '../zod.ts';
+import { ProofResponseWireSchema } from './wire.ts';
+
+export const addProofRoutes = <
+  Ops extends Record<string, RouteWithOpId>,
+  Schemes extends Record<string, true>
+>(
+  r: TypedRegistry<Ops, Schemes>
+) =>
+  r.registerPath({
+    operationId: 'getProof',
+    method: 'get',
+    path: '/v1/{network}/distributions/{distributionId}/allocations/{address}/proof',
+    summary: 'Get the merkle proof for a single allocation',
+    description:
+      'Rebuilds (or cache-hits) the merkle tree from the persisted allocations ' +
+      'table and extracts the proof for the requested address. The returned ' +
+      'tuple `(merkleRoot, address, amount, leafIndex, proof)` can be passed ' +
+      'straight to a Solidity verifier built around the same `[address, uint256]` ' +
+      'leaf encoding.',
+    request: {
+      params: z.object({
+        network: NetworkSchema,
+        distributionId: DistributionIdSchema,
+        address: AddressSchema
+      })
+    },
+    responses: {
+      200: {
+        description: 'Proof bundle ready to submit to the claimer contract.',
+        content: { 'application/json': { schema: ProofResponseWireSchema } }
+      },
+      404: {
+        description:
+          'Distribution not found, not yet completed, address has no allocation, ' +
+          'or the allocation is excluded from the tree (settled off-chain).',
+        content: { 'application/json': { schema: ErrorResponseSchema } }
+      }
+    }
+  });

package/src/routes-public/wire.ts

@@ -0,0 +1,74 @@
+// Wire-shape response variants for the public-API registry.
+//
+// The registry-driven router (`@polygonlabs/express/registry`) re-encodes
+// every response through `z.encode` before send. `AddressSchema` carries a
+// unidirectional `.transform()` (request-boundary lowercasing) which
+// `z.encode` rejects ("Encountered unidirectional transform during
+// encode"), so response slots cannot reference it or any schema embedding
+// it. The variants below override only the `address` field with a
+// no-transform lowercase-address schema; the wire contract is unchanged
+// because handlers always emit lowercased addresses (the DB stores them
+// lowercased and request params are normalised on the way in). Every other
+// field is reused from the canonical schema by reference (`.shape`
+// spread), so a field added or changed upstream flows through.
+//
+// Built via `z.object({ ...Parent.shape, address })` rather than
+// `.extend()`: an `.extend()` child keeps zod-to-openapi lineage to its
+// parent and generates as `allOf` + `$ref` to a parent component, but both
+// parent and child here deliberately carry the same `.openapi('Name')`
+// registration (the component names are the public contract), which would
+// collide at generation time. A fresh `z.object` has no lineage, so each
+// name resolves to exactly one component.
+import { AllocationHistoryRowSchema } from '../allocation-history.ts';
+import {
+  AllocationListResponseSchema,
+  AllocationRowSchema,
+  ExcludedAllocationRowSchema,
+  ExcludedAllocationsResponseSchema
+} from '../allocation.ts';
+import { ProofResponseSchema } from '../proof.ts';
+import { z } from '../zod.ts';
+
+// Lowercased 0x-prefixed 40-hex EVM address as it appears on the wire.
+// Response-side counterpart of `AddressSchema` (which lowercases via a
+// transform and therefore can't be encoded).
+const ApiAddressSchema = z
+  .string()
+  .regex(/^0x[0-9a-f]{40}$/)
+  .openapi({ example: '0xabc0000000000000000000000000000000000001' });
+
+export const AllocationRowWireSchema = z
+  .object({ ...AllocationRowSchema.shape, address: ApiAddressSchema })
+  .openapi('AllocationRow');
+
+export const AllocationListResponseWireSchema = z
+  .object({
+    ...AllocationListResponseSchema.shape,
+    items: z.array(AllocationRowWireSchema)
+  })
+  .openapi('AllocationListResponse');
+
+export const ExcludedAllocationRowWireSchema = z
+  .object({ ...ExcludedAllocationRowSchema.shape, address: ApiAddressSchema })
+  .openapi('ExcludedAllocationRow');
+
+export const ExcludedAllocationsResponseWireSchema = z
+  .object({
+    ...ExcludedAllocationsResponseSchema.shape,
+    items: z.array(ExcludedAllocationRowWireSchema)
+  })
+  .openapi('ExcludedAllocationsResponse');
+
+export const AllocationHistoryRowWireSchema = z
+  .object({ ...AllocationHistoryRowSchema.shape, address: ApiAddressSchema })
+  .openapi('AllocationHistoryRow');
+
+export const AllocationHistoryResponseWireSchema = z
+  .object({
+    items: z.array(AllocationHistoryRowWireSchema)
+  })
+  .openapi('AllocationHistoryResponse');
+
+export const ProofResponseWireSchema = z
+  .object({ ...ProofResponseSchema.shape, address: ApiAddressSchema })
+  .openapi('ProofResponse');