tapimo 0.14.0 → 0.15.1

package/src/admin/apps/earn-vaults.ts

@@ -4,7 +4,13 @@ import * as z from 'zod/mini'
 import * as Earn from '../../apps/data/routes/earn.js'
 import * as Db from '../../db/Db.js'
 import * as core_EarnVaults from '../../db/tables/earnVaults.js'
+import * as RewardAccounts from '../../db/tables/rewardAccounts.js'
+import * as RewardCampaigns from '../../db/tables/rewardCampaigns.js'
+import * as RewardRuns from '../../db/tables/rewardRuns.js'
+import * as RewardTransactionAttempts from '../../db/tables/rewardTransactionAttempts.js'
 import * as Cursor from '../../internal/Cursor.js'
+import * as Campaigns from '../../internal/rewards/Campaigns.js'
+import * as RewardRead from '../../internal/rewards/Read.js'
 import * as EarnVaults from '../../internal/EarnVaults.js'
 import * as OpenApi from '../../internal/OpenApi.js'
 import * as Path from '../../internal/Path.js'
@@ -116,6 +122,294 @@ export namespace schema {
       .strictObject({ chainId: Schema.ChainId })
       .check(z.describe('Query parameters selecting one verified Earn vault.'))
   }
+
+  /** Shared reward campaign response. */
+  export const RewardCampaign = z
+    .strictObject({
+      chainId: Schema.ChainId,
+      config: Campaigns.schema.Config,
+      controllerAddress: z
+        .nullable(Schema.Address)
+        .check(
+          z.describe('Target-yield controller address, or null before provisioning.'),
+          z.meta({ examples: ['0x7000000000000000000000000000000000000007'] }),
+        ),
+      deliveredThrough: z
+        .string()
+        .check(
+          z.regex(/^\d+$/),
+          z.describe('Last fully delivered Unix interval boundary.'),
+          z.meta({ examples: ['1788192000'] }),
+        ),
+      distributorAddress: z
+        .nullable(Schema.Address)
+        .check(
+          z.describe('Merkle distributor address, or null before provisioning.'),
+          z.meta({ examples: ['0x8000000000000000000000000000000000000008'] }),
+        ),
+      eventCursor: z
+        .nullable(
+          z
+            .strictObject({
+              blockNumber: z
+                .number()
+                .check(
+                  z.int(),
+                  z.nonnegative(),
+                  z.describe('Last applied event block number.'),
+                  z.meta({ examples: [123456] }),
+                ),
+              logIndex: z
+                .number()
+                .check(
+                  z.int(),
+                  z.nonnegative(),
+                  z.describe('Last applied event log index.'),
+                  z.meta({ examples: [2] }),
+                ),
+              transactionIndex: z
+                .number()
+                .check(
+                  z.int(),
+                  z.nonnegative(),
+                  z.describe('Last applied event transaction index.'),
+                  z.meta({ examples: [1] }),
+                ),
+            })
+            .check(z.describe('Last applied TIDX event cursor.')),
+        )
+        .check(z.describe('Last applied TIDX event cursor, or null before indexing.')),
+      execution: z.nullable(
+        z
+          .strictObject({
+            boostRateBps: z.nullable(
+              z
+                .number()
+                .check(
+                  z.int(),
+                  z.nonnegative(),
+                  z.describe('Measured boost APR in basis points.'),
+                  z.meta({ examples: [392] }),
+                ),
+            ),
+            endsAt: z
+              .string()
+              .check(
+                z.regex(/^\d+$/),
+                z.describe('Exclusive execution end boundary.'),
+                z.meta({ examples: ['1788192000'] }),
+              ),
+            error: z.nullable(
+              z
+                .string()
+                .check(
+                  z.describe('Latest execution error.'),
+                  z.meta({ examples: ['Reward signer is unavailable.'] }),
+                ),
+            ),
+            fundedAssets: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Base assets funded during target-yield settlement.'),
+                z.meta({ examples: ['1000000'] }),
+              ),
+            id: z
+              .string()
+              .check(
+                z.describe('Durable reward-run identifier.'),
+                z.meta({ examples: ['rrn_0123456789abcdefghijklmn'] }),
+              ),
+            intervalCount: z
+              .number()
+              .check(
+                z.int(),
+                z.nonnegative(),
+                z.describe('Number of intervals covered by the run.'),
+                z.meta({ examples: [1] }),
+              ),
+            liability: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('Cumulative EarnShare liability committed by the run.'),
+                z.meta({ examples: ['500000'] }),
+              ),
+            mintedEarnShares: z
+              .nullable(Schema.DecimalString)
+              .check(
+                z.describe('EarnShare minted while funding boost settlement.'),
+                z.meta({ examples: ['500000'] }),
+              ),
+            organicRateBps: z.nullable(
+              z
+                .number()
+                .check(
+                  z.int(),
+                  z.nonnegative(),
+                  z.describe('Latest contribution-adjusted interval APR in basis points.'),
+                  z.meta({ examples: [108] }),
+                ),
+            ),
+            phase: z
+              .enum([
+                'indexing',
+                'calculating',
+                'targetYield',
+                'statement',
+                'settling',
+                'publishing',
+                'paying',
+                'delivered',
+                'failed',
+              ])
+              .check(
+                z.describe('Current durable execution phase.'),
+                z.meta({ examples: ['delivered'] }),
+              ),
+            rootVersion: z
+              .nullable(z.string().check(z.regex(/^\d+$/)))
+              .check(
+                z.describe('Confirmed distributor root version.'),
+                z.meta({ examples: ['7'] }),
+              ),
+            startsAfter: z
+              .string()
+              .check(
+                z.regex(/^\d+$/),
+                z.describe('Previously delivered boundary where the run starts.'),
+                z.meta({ examples: ['1788191700'] }),
+              ),
+            statementHash: z
+              .nullable(Schema.Hash)
+              .check(
+                z.describe('Confirmed reward statement hash.'),
+                z.meta({ examples: [`0x${'11'.repeat(32)}`] }),
+              ),
+            targetRateBps: z.nullable(
+              z
+                .number()
+                .check(
+                  z.int(),
+                  z.nonnegative(),
+                  z.describe('Target total APR in basis points.'),
+                  z.meta({ examples: [500] }),
+                ),
+            ),
+            transactions: z
+              .array(
+                z.strictObject({
+                  expiresAt: z.nullable(
+                    z
+                      .string()
+                      .check(
+                        z.describe('Transaction expiry timestamp.'),
+                        z.meta({ examples: ['2026-08-31T12:00:00.000Z'] }),
+                      ),
+                  ),
+                  hash: z
+                    .nullable(Schema.Hash)
+                    .check(
+                      z.describe('Signed transaction hash.'),
+                      z.meta({ examples: [`0x${'22'.repeat(32)}`] }),
+                    ),
+                  operation: z
+                    .enum(['deploy', 'targetYield', 'settle', 'publish', 'push'])
+                    .check(
+                      z.describe('Reward operation encoded by the transaction.'),
+                      z.meta({ examples: ['push'] }),
+                    ),
+                  state: z
+                    .enum([
+                      'created',
+                      'signed',
+                      'broadcast',
+                      'confirmed',
+                      'expired',
+                      'ineffective',
+                      'reverted',
+                    ])
+                    .check(
+                      z.describe('Durable transaction-attempt state.'),
+                      z.meta({ examples: ['confirmed'] }),
+                    ),
+                  updatedAt: z
+                    .string()
+                    .check(
+                      z.describe('Last transaction-attempt update (ISO 8601).'),
+                      z.meta({ examples: ['2026-08-31T12:00:00.000Z'] }),
+                    ),
+                }),
+              )
+              .check(z.describe('Transaction attempts belonging to the execution.')),
+            updatedAt: z
+              .string()
+              .check(
+                z.describe('Last execution update (ISO 8601).'),
+                z.meta({ examples: ['2026-08-31T12:00:00.000Z'] }),
+              ),
+          })
+          .check(z.describe('Latest reward execution.')),
+      ),
+      paused: z
+        .boolean()
+        .check(z.describe('Whether new campaign work is paused.'), z.meta({ examples: [false] })),
+      pendingConfig: z
+        .nullable(Campaigns.schema.Config)
+        .check(z.describe('Complete configuration scheduled for a future boundary.')),
+      pendingEffectiveAt: z
+        .nullable(z.string().check(z.regex(/^\d+$/)))
+        .check(
+          z.describe('Unix boundary when pending configuration becomes active.'),
+          z.meta({ examples: ['1788192300'] }),
+        ),
+      peripheryReady: z
+        .boolean()
+        .check(
+          z.describe('Whether required reward periphery is provisioned.'),
+          z.meta({ examples: [true] }),
+        ),
+      provisioningError: z
+        .nullable(z.string())
+        .check(
+          z.describe('Latest reward-periphery provisioning error.'),
+          z.meta({ examples: ['Reward signer is unavailable.'] }),
+        ),
+      signerAddress: z
+        .nullable(Schema.Address)
+        .check(
+          z.describe('Signer permanently bound to the reward periphery.'),
+          z.meta({ examples: ['0x9000000000000000000000000000000000000009'] }),
+        ),
+      unpaidEarnShares: Schema.DecimalString.check(
+        z.describe('Current unpaid EarnShare across all recipients.'),
+        z.meta({ examples: ['0'] }),
+      ),
+      unpaidRecipients: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Recipients with a positive unpaid balance.'),
+          z.meta({ examples: [0] }),
+        ),
+      vaultAddress: Schema.Address.check(z.describe('EarnVault address identifying the campaign.')),
+    })
+    .check(z.describe('Current reward campaign configuration and execution state.'))
+
+  /** Schemas for reward campaign administration. */
+  export namespace rewardCampaign {
+    /** Complete campaign configuration. */
+    export const Body = Campaigns.schema.Config.check(
+      z.describe('Complete reward configuration for one verified Earn vault.'),
+    )
+    /** Path parameters identifying one verified vault. */
+    export const Params = Earn.schema.getEarnVault.Params
+    /** Query parameters selecting the vault chain. */
+    export const Query = z
+      .strictObject({ chainId: Schema.ChainId })
+      .check(z.describe('Query parameters selecting one verified Earn vault.'))
+    /** Current campaign configuration and readiness. */
+    export const Response = RewardCampaign
+  }
 }
 
 /** Admin routes for reading and managing verified Earn vaults. */
@@ -193,6 +487,241 @@ export function earnVaults() {
         }
       },
     )
+    .get(
+      '/:vaultId/rewards',
+      OpenApi.validate('param', schema.rewardCampaign.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+      }),
+      OpenApi.validate('query', schema.rewardCampaign.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'getEarnRewardCampaign',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              codes: ['earn_reward_campaign_not_found'],
+              description: 'The reward campaign was not found.',
+            },
+          },
+          success: {
+            description: 'The configured reward campaign.',
+            schema: schema.rewardCampaign.Response,
+          },
+        }),
+        summary: 'Get reward campaign',
+        tags: ['Earn Vaults'],
+      }),
+      async (c) => {
+        const { vaultId } = c.req.valid('param')
+        const { chainId } = c.req.valid('query')
+        const db = Db.get(c.get('db'))
+        const campaign = await RewardCampaigns.get(db, {
+          chainId,
+          vaultAddress: vaultId,
+        })
+        if (!campaign)
+          return Response.error(c, {
+            code: 'earn_reward_campaign_not_found',
+            message: 'Reward campaign not found',
+            status: 404,
+          })
+        let unpaid: RewardAccounts.unpaid.Result
+        try {
+          unpaid = await RewardRead.unpaid({
+            campaign,
+            db,
+            getClient: c.get('getClient'),
+          })
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+        return c.json(
+          Response.validated(
+            schema.rewardCampaign.Response,
+            await serializeCampaign(db, {
+              campaign,
+              unpaid,
+            }),
+          ),
+          200,
+        )
+      },
+    )
+    .post(
+      '/:vaultId/rewards',
+      OpenApi.validate('param', schema.rewardCampaign.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+      }),
+      OpenApi.validate('query', schema.rewardCampaign.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.validate('json', schema.rewardCampaign.Body, {
+        code: 'body_invalid',
+        message: 'Invalid reward configuration',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'postEarnRewardCampaign',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              codes: ['earn_vault_not_found'],
+              description: 'The verified vault was not found.',
+            },
+            409: {
+              codes: ['earn_reward_campaign_invalid'],
+              description: 'The configuration cannot replace the active campaign.',
+            },
+          },
+          success: {
+            description: 'The configured reward campaign.',
+            schema: schema.rewardCampaign.Response,
+          },
+        }),
+        summary: 'Configure reward campaign',
+        tags: ['Earn Vaults'],
+      }),
+      async (c) => {
+        const { vaultId } = c.req.valid('param')
+        const { chainId } = c.req.valid('query')
+        const config = c.req.valid('json')
+        if (chainId !== Viem.chainId.mainnet)
+          return Response.error(c, {
+            code: 'earn_reward_campaign_invalid',
+            message: 'Reward campaigns are currently supported only on Tempo mainnet.',
+            status: 409,
+          })
+        const db = Db.get(c.get('db'))
+        const verified = await core_EarnVaults.get(db, { chainId, vaultAddress: vaultId })
+        if (!verified) return notFound(c)
+        const now = Math.floor(Date.now() / 1_000)
+        const existing = await RewardCampaigns.get(db, { chainId, vaultAddress: vaultId })
+        const startsAt = Math.min(
+          config.targetYield?.startTimestamp ?? Number.MAX_SAFE_INTEGER,
+          config.boostRewards?.startTimestamp ?? Number.MAX_SAFE_INTEGER,
+        )
+        if (!existing && startsAt <= now)
+          return Response.error(c, {
+            code: 'earn_reward_campaign_invalid',
+            message: 'A new reward campaign must start on a future interval boundary.',
+            status: 409,
+          })
+        try {
+          const discovery = await EarnVaults.resolve({
+            getClient: c.get('getClient'),
+            input: { chainId, vaultAddress: vaultId },
+            zones: c.get('zones'),
+          })
+          if (discovery.assetToken.currency !== 'USD')
+            return Response.error(c, {
+              code: 'earn_reward_campaign_invalid',
+              message: 'Reward campaigns currently require a USD-denominated base asset.',
+              status: 409,
+            })
+          const campaign = await RewardCampaigns.upsert(db, {
+            assetAddress: discovery.assetToken.address,
+            assetDecimals: discovery.assetToken.decimals,
+            chainId,
+            config,
+            earnShareAddress: discovery.shareToken.address,
+            earnShareDecimals: discovery.shareToken.decimals,
+            now,
+            vaultAddress: discovery.vaultAddress,
+          })
+          const unpaid = await RewardAccounts.unpaid(db, campaign)
+          return c.json(
+            Response.validated(
+              schema.rewardCampaign.Response,
+              await serializeCampaign(db, {
+                campaign,
+                unpaid,
+              }),
+            ),
+            200,
+          )
+        } catch (cause) {
+          if (cause instanceof RewardCampaigns.ConfigurationError)
+            return Response.error(c, {
+              code: 'earn_reward_campaign_invalid',
+              message: cause.message,
+              status: 409,
+            })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/:vaultId/rewards/pause',
+      OpenApi.validate('param', schema.rewardCampaign.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+      }),
+      OpenApi.validate('query', schema.rewardCampaign.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'pauseEarnRewardCampaign',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              codes: ['earn_reward_campaign_not_found'],
+              description: 'The reward campaign was not found.',
+            },
+          },
+          success: {
+            description: 'The paused reward campaign.',
+            schema: schema.rewardCampaign.Response,
+          },
+        }),
+        summary: 'Pause reward campaign',
+        tags: ['Earn Vaults'],
+      }),
+      async (c) =>
+        updateCampaignPause(c, {
+          chainId: c.req.valid('query').chainId,
+          paused: true,
+          vaultAddress: c.req.valid('param').vaultId,
+        }),
+    )
+    .post(
+      '/:vaultId/rewards/resume',
+      OpenApi.validate('param', schema.rewardCampaign.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+      }),
+      OpenApi.validate('query', schema.rewardCampaign.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'resumeEarnRewardCampaign',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              codes: ['earn_reward_campaign_not_found'],
+              description: 'The reward campaign was not found.',
+            },
+          },
+          success: {
+            description: 'The resumed reward campaign.',
+            schema: schema.rewardCampaign.Response,
+          },
+        }),
+        summary: 'Resume reward campaign',
+        tags: ['Earn Vaults'],
+      }),
+      async (c) =>
+        updateCampaignPause(c, {
+          chainId: c.req.valid('query').chainId,
+          paused: false,
+          vaultAddress: c.req.valid('param').vaultId,
+        }),
+    )
     .put(
       '/',
       OpenApi.validate('json', schema.putVerifiedEarnVault.Body, {
@@ -305,6 +834,9 @@ export function earnVaults() {
           404: OpenApi.standardError(404, 'Verified Earn vault not found.', [
             'earn_vault_not_found',
           ]),
+          409: OpenApi.standardError(409, 'The vault has retained reward campaign history.', [
+            'earn_vault_rewards_exist',
+          ]),
           429: OpenApi.standardError(429, 'Rate limited.'),
           500: OpenApi.standardError(500, 'Internal server error.'),
         },
@@ -314,16 +846,145 @@ export function earnVaults() {
       async (c) => {
         const { vaultId } = c.req.valid('param')
         const { chainId } = c.req.valid('query')
-        const record = await core_EarnVaults.remove(Db.get(c.get('db')), {
-          chainId,
-          vaultAddress: vaultId,
-        })
-        if (!record) return notFound(c)
-        return c.body(null, 204)
+        try {
+          const record = await core_EarnVaults.remove(Db.get(c.get('db')), {
+            chainId,
+            vaultAddress: vaultId,
+          })
+          if (!record) return notFound(c)
+          return c.body(null, 204)
+        } catch (cause) {
+          if (isRewardCampaignConstraint(cause))
+            return Response.error(c, {
+              code: 'earn_vault_rewards_exist',
+              message:
+                'A vault with reward campaign history cannot be removed because recovery claims remain available.',
+              status: 409,
+            })
+          throw cause
+        }
       },
     )
 }
 
+async function serializeCampaign(
+  db: Db.Db,
+  options: serializeCampaign.Options,
+): Promise<z.output<typeof schema.rewardCampaign.Response>> {
+  const { campaign, unpaid } = options
+  const execution = await RewardRuns.latestSummary(db, campaign)
+  const attempts = execution ? await RewardTransactionAttempts.listForRun(db, execution.id) : []
+  return {
+    chainId: campaign.chainId,
+    config: campaign.config,
+    controllerAddress: campaign.controllerAddress,
+    deliveredThrough: campaign.deliveredThrough,
+    distributorAddress: campaign.distributorAddress,
+    eventCursor: campaign.eventCursor,
+    execution: execution
+      ? {
+          boostRateBps: execution.evidence?.boostRateBps ?? null,
+          endsAt: execution.endsAt,
+          error: execution.error,
+          fundedAssets: execution.fundedAssets,
+          id: execution.id,
+          intervalCount: execution.evidence?.intervals.length ?? 0,
+          liability: execution.liability,
+          mintedEarnShares: execution.mintedEarnShares,
+          organicRateBps: execution.evidence?.organicRateBps ?? null,
+          phase: execution.phase,
+          rootVersion: execution.rootVersion,
+          startsAfter: execution.startsAfter,
+          statementHash: execution.statementHash,
+          targetRateBps: execution.evidence?.targetRateBps ?? null,
+          transactions: attempts.map((attempt) => ({
+            expiresAt: attempt.expiresAt,
+            hash: attempt.transactionHash,
+            operation: attempt.intent.operation,
+            state: attempt.state,
+            updatedAt: attempt.updatedAt,
+          })),
+          updatedAt: execution.updatedAt,
+        }
+      : null,
+    paused: campaign.paused,
+    pendingConfig: campaign.pendingConfig,
+    pendingEffectiveAt: campaign.pendingEffectiveAt,
+    provisioningError: campaign.provisioningError,
+    signerAddress: campaign.signerAddress,
+    peripheryReady:
+      !campaign.provisioningError &&
+      [campaign.config, campaign.pendingConfig].every(
+        (config) =>
+          !config ||
+          ((!config.targetYield || campaign.controllerAddress !== null) &&
+            (!config.boostRewards || campaign.distributorAddress !== null)),
+      ),
+    unpaidEarnShares: unpaid.earnShares,
+    unpaidRecipients: unpaid.recipients,
+    vaultAddress: campaign.vaultAddress,
+  }
+}
+
+declare namespace serializeCampaign {
+  /** Campaign serialization dependencies. */
+  type Options = {
+    /** Stored reward campaign. */
+    campaign: RewardCampaigns.Record
+    /** Unpaid totals selected by the caller's consistency boundary. */
+    unpaid: RewardAccounts.unpaid.Result
+  }
+}
+
+async function updateCampaignPause(
+  c: Context<App.Environment>,
+  options: updateCampaignPause.Options,
+) {
+  const db = Db.get(c.get('db'))
+  const campaign = await RewardCampaigns.setPaused(db, {
+    chainId: options.chainId,
+    paused: options.paused,
+    vaultAddress: options.vaultAddress,
+  })
+  if (!campaign)
+    return Response.error(c, {
+      code: 'earn_reward_campaign_not_found',
+      message: 'Reward campaign not found',
+      status: 404,
+    })
+  let unpaid: RewardAccounts.unpaid.Result
+  try {
+    unpaid = await RewardRead.unpaid({
+      campaign,
+      db,
+      getClient: c.get('getClient'),
+    })
+  } catch {
+    // Pausing is an operational safety action and must remain available during RPC incidents.
+    // The next healthy read or scheduler pass reconciles permissionless claims.
+    unpaid = await RewardAccounts.unpaid(db, campaign)
+  }
+  return c.json(
+    Response.validated(
+      schema.rewardCampaign.Response,
+      await serializeCampaign(db, { campaign, unpaid }),
+    ),
+    200,
+  )
+}
+
+declare namespace updateCampaignPause {
+  /** Validated campaign pause mutation. */
+  type Options = {
+    /** Chain containing the campaign. */
+    chainId: number
+    /** Replacement pause state. */
+    paused: boolean
+    /** EarnVault identifying the campaign. */
+    vaultAddress: string
+  }
+}
+
 async function listVerifiedVaults(
   c: Context<App.Environment>,
   options: listVerifiedVaults.Options,
@@ -632,6 +1293,18 @@ function mutationError(c: Context<App.Environment>, cause: unknown) {
   return Response.upstream(c, cause)
 }
 
+function isRewardCampaignConstraint(
+  cause: unknown,
+): cause is { code: '23503'; constraint: 'reward_campaigns_vault_fkey' } {
+  return (
+    cause instanceof Error &&
+    'code' in cause &&
+    cause.code === '23503' &&
+    'constraint' in cause &&
+    cause.constraint === 'reward_campaigns_vault_fkey'
+  )
+}
+
 function notFound(c: Context<App.Environment>, message = 'Verified Earn vault not found') {
   return Response.error(c, {
     code: 'earn_vault_not_found',