tapimo 0.14.0 → 0.15.0

package/src/internal/rewards/Signer.test.ts

@@ -0,0 +1,79 @@
+import { expect, test } from 'vitest'
+
+import * as Signer from './Signer.js'
+
+const intent = {
+  boostRewards: true,
+  domain: {
+    chainId: 4217,
+    earnShare: '0x0000000000000000000000000000000000000002',
+    earnVault: '0x0000000000000000000000000000000000000001',
+    factory: '0x0000000000000000000000000000000000000003',
+    treasury: '0x0000000000000000000000000000000000000004',
+  },
+  operation: 'deploy',
+  targetYield: false,
+  treasury: '0x0000000000000000000000000000000000000004',
+} as const
+
+test('id deterministically binds the complete typed intent', () => {
+  expect(Signer.id(intent)).toBe(Signer.id({ ...intent }))
+  expect(Signer.id({ ...intent, boostRewards: false })).not.toBe(Signer.id(intent))
+})
+
+test('id normalizes address casing before hashing', () => {
+  const mixedCase = {
+    ...intent,
+    domain: {
+      ...intent.domain,
+      earnVault: '0xD730394F3Bb85A4828E35fc5e361DCC9F894fa4F',
+    },
+  } as const
+  const normalized = Signer.schema.Intent.parse(mixedCase)
+
+  expect(Signer.id(mixedCase)).toBe(Signer.id(normalized))
+})
+
+test('uses the deployed single-funder controller path', () => {
+  expect([Signer.targetYieldFunction(1), Signer.targetYieldFunction(2)]).toStrictEqual([
+    'fund',
+    'fundBatchExact',
+  ])
+  expect(() => Signer.targetYieldFunction(0)).toThrow('at least one funder')
+})
+
+test('schema accepts at most two gas-bounded payout calls per transaction', () => {
+  const payout = {
+    batches: [
+      {
+        cumulativeAmounts: ['1'],
+        multiproof: [],
+        proofFlags: [],
+        recipients: [intent.domain.earnVault],
+      },
+      {
+        cumulativeAmounts: ['2'],
+        multiproof: [],
+        proofFlags: [],
+        recipients: [intent.domain.earnShare],
+      },
+    ],
+    distributor: intent.domain.earnShare,
+    domain: intent.domain,
+    operation: 'push',
+    rootVersion: '1',
+    statementHash: `0x${'11'.repeat(32)}`,
+  }
+  const request = {
+    attemptId: 'rat_000000000000000000000000',
+    id: `0x${'22'.repeat(32)}`,
+    intent: payout,
+  }
+  expect([
+    Signer.schema.Request.safeParse(request).success,
+    Signer.schema.Request.safeParse({
+      ...request,
+      intent: { ...payout, batches: [...payout.batches, payout.batches[0]!] },
+    }).success,
+  ]).toStrictEqual([true, false])
+})

package/src/internal/rewards/Signer.ts

@@ -0,0 +1,180 @@
+import { keccak256, stringToHex, zeroAddress, type Address, type Hex } from 'viem'
+import * as z from 'zod/mini'
+
+import * as Campaigns from './Campaigns.js'
+import * as Schema from '../Schema.js'
+
+const uint = Schema.DecimalString
+const hash = Schema.Hash
+const address = Schema.Address.check(
+  z.refine((value) => value !== zeroAddress, { error: 'address must be nonzero' }),
+)
+
+/** Zod schemas for the isolated reward signer protocol. */
+export namespace schema {
+  const Domain = z.strictObject({
+    chainId: Schema.ChainId,
+    earnShare: address,
+    earnVault: address,
+    factory: address,
+    treasury: Schema.Address,
+  })
+
+  const Install = z.strictObject({
+    boostRewards: z.boolean(),
+    domain: Domain,
+    operation: z.literal('deploy'),
+    targetYield: z.boolean(),
+    treasury: Schema.Address,
+  })
+
+  const TargetYield = z.strictObject({
+    controller: address,
+    domain: Domain,
+    funders: z.array(address).check(z.minLength(1)),
+    maxEarnShareSupply: uint,
+    operation: z.literal('targetYield'),
+    requestedAssets: z.array(uint).check(z.minLength(1)),
+  })
+
+  const Publish = z.strictObject({
+    distributor: address,
+    domain: Domain,
+    expectedRootVersion: uint,
+    operation: z.literal('publish'),
+    statement: z.custom<Campaigns.Statement>(),
+  })
+
+  const Settle = z.strictObject({
+    assets: uint,
+    distributor: address,
+    domain: Domain,
+    expectedRootVersion: uint,
+    funder: address,
+    minEarnShares: uint,
+    operation: z.literal('settle'),
+    settlementId: hash,
+    statement: z.custom<Campaigns.Statement>(),
+  })
+
+  const Push = z.strictObject({
+    batches: z.array(z.custom<Campaigns.PayoutBatch>()).check(z.minLength(1), z.maxLength(2)),
+    distributor: address,
+    domain: Domain,
+    operation: z.literal('push'),
+    rootVersion: uint,
+    statementHash: hash,
+  })
+
+  /** One typed reward operation accepted by the isolated signer. */
+  export const Intent = z.discriminatedUnion('operation', [
+    Install,
+    Publish,
+    Push,
+    Settle,
+    TargetYield,
+  ])
+
+  /** One complete typed signing request. */
+  export const Request = z.strictObject({
+    attemptId: z.string().check(z.regex(/^rat_[0-9a-z]{24}$/)),
+    id: hash,
+    intent: Intent,
+  })
+
+  /** Exact signed transaction returned before broadcast. */
+  export const Response = z.strictObject({
+    expiresAt: z.nullable(z.string()),
+    nonce: z.nullable(uint),
+    signedBytes: Schema.Hex,
+    signer: Schema.Address,
+    transactionHash: hash,
+  })
+
+  /** Public readiness returned by the signer without exposing secrets. */
+  export const Health = z.strictObject({ ok: z.literal(true), signer: Schema.Address })
+}
+
+/** One complete typed signing request. */
+export type Request = z.output<typeof schema.Request>
+
+/** Exact signed transaction returned before broadcast. */
+export type Response = z.output<typeof schema.Response>
+
+/** Reads the isolated signer's readiness and public account. */
+export async function health(
+  fetch: typeof globalThis.fetch,
+): Promise<z.output<typeof schema.Health>> {
+  const response = await fetch('https://earn-reward-signer.internal/health')
+  if (!response.ok) throw new Error(`Reward signer health responded ${response.status}.`)
+  return schema.Health.parse(await response.json())
+}
+
+/** Returns a deterministic id for one typed signer intent. */
+export function id(intent: Request['intent']): Hex {
+  return keccak256(stringToHex(canonical(schema.Intent.parse(intent))))
+}
+
+/** Selects the deployed controller entrypoint for one nonempty funding set. */
+export function targetYieldFunction(funderCount: number): 'fund' | 'fundBatchExact' {
+  if (!Number.isInteger(funderCount) || funderCount < 1)
+    throw new Error('target-yield funding requires at least one funder')
+  return funderCount === 1 ? 'fund' : 'fundBatchExact'
+}
+
+/** Requests one typed signature from the isolated signer Worker. */
+export async function sign(options: sign.Options): Promise<Response> {
+  const request = schema.Request.parse(options.request)
+  if (id(request.intent) !== request.id) throw new Error('reward signer intent id mismatch')
+  const response = await options.fetch('https://earn-reward-signer.internal/v1/sign', {
+    body: JSON.stringify(request),
+    headers: { 'content-type': 'application/json' },
+    method: 'POST',
+  })
+  if (!response.ok) {
+    const fallback = `Reward signer responded ${response.status}.`
+    const body = await response.text()
+    let message: unknown
+    try {
+      message = (JSON.parse(body) as { error?: unknown }).error
+    } catch {
+      message = undefined
+    }
+    throw new Error(typeof message === 'string' && message ? message.slice(0, 500) : fallback)
+  }
+  return schema.Response.parse(await response.json())
+}
+
+export declare namespace sign {
+  /** Typed signer request transport. */
+  type Options = {
+    /** Isolated signer service fetch. */
+    fetch: typeof globalThis.fetch
+    /** Complete typed request. */
+    request: Request
+  }
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object')
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+      .join(',')}}`
+  return JSON.stringify(value)
+}
+
+/** Address fields required by one signer request. */
+export type Domain = {
+  /** Supported Tempo chain. */
+  chainId: number
+  /** Vault EarnShare. */
+  earnShare: Address
+  /** Bound EarnVault. */
+  earnVault: Address
+  /** Reviewed rewards factory. */
+  factory: Address
+  /** Immutable reward treasury, or zero when no boost distributor exists. */
+  treasury: Address
+}

package/src/internal/rewards/index.ts

@@ -0,0 +1,14 @@
+/** Pure campaign configuration, accrual, allocation, and Merkle primitives. */
+export * as Campaigns from './Campaigns.js'
+/** TIDX-backed reward event access. */
+export * as Events from './Events.js'
+/** Registered-recipient balance and qualification projection. */
+export * as Projection from './Projection.js'
+/** Target-rate resolution. */
+export * as Rates from './Rates.js'
+/** Public reward metadata, recipient state, and proof reads. */
+export * as Read from './Read.js'
+/** Durable campaign execution coordinator. */
+export * as Runner from './Runner.js'
+/** Typed protocol for the isolated reward signer. */
+export * as Signer from './Signer.js'

package/src/internal/{funding → routes}/Action.test.ts

@@ -3,14 +3,22 @@ import * as Action from './Action.js'
 const sourceToken = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
 const spender = `0x${'44'.repeat(20)}`
 
-function approveCall(amount: bigint): Action.Call {
+function approveCall(amount: bigint, options: approveCall.Options = {}): Action.Call {
+  const target = options.spender ?? spender
   return {
-    data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${amount.toString(16).padStart(64, '0')}`,
-    to: sourceToken,
+    data: `0x095ea7b3${target.slice(2).padStart(64, '0')}${amount.toString(16).padStart(64, '0')}`,
+    to: options.token ?? sourceToken,
     value: '0x0',
   }
 }
 
+declare namespace approveCall {
+  type Options = {
+    spender?: string | undefined
+    token?: string | undefined
+  }
+}
+
 const depositCall: Action.Call = { data: '0xe8017952', to: spender, value: '0x0' }
 
 describe('validateEvmCalls', () => {
@@ -30,7 +38,7 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Approval must stay bounded to the route amount.]`,
+      `[Routes.Action.InvalidActionError: Approval must stay bounded to the route amount.]`,
     )
   })
 
@@ -48,14 +56,57 @@ describe('validateEvmCalls', () => {
     expect(() =>
       Action.validateEvmCalls({
         action: {
-          calls: [{ ...approveCall(1n), to: `0x${'99'.repeat(20)}` }],
+          calls: [{ ...approveCall(1n), to: `0x${'99'.repeat(20)}` }, depositCall],
           type: 'evm:calls',
         },
         sourceAmount: '1000000',
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Approval must target the source token.]`,
+      `[Routes.Action.InvalidActionError: Approval must stay bounded to the route amount.]`,
+    )
+  })
+
+  test('accepts an exact provider-validated approval for another token', () => {
+    const feeToken = `0x${'99'.repeat(20)}`
+    Action.validateEvmCalls({
+      action: {
+        calls: [approveCall(2_000_000n, { token: feeToken }), depositCall],
+        type: 'evm:calls',
+      },
+      sourceAmount: '1000000',
+      sourceTokenAddress: sourceToken,
+      tokenApprovals: [{ amount: '2000000', spender, token: feeToken }],
+    })
+  })
+
+  test('rejects approvals outside the exact provider token allowance', () => {
+    const feeToken = `0x${'99'.repeat(20)}`
+    for (const call of [
+      approveCall(2_000_001n, { token: feeToken }),
+      approveCall(2_000_000n, { spender: `0x${'88'.repeat(20)}`, token: feeToken }),
+      approveCall(2_000_000n, { token: `0x${'77'.repeat(20)}` }),
+    ])
+      expect(() =>
+        Action.validateEvmCalls({
+          action: { calls: [call, depositCall], type: 'evm:calls' },
+          sourceAmount: '1000000',
+          sourceTokenAddress: sourceToken,
+          tokenApprovals: [{ amount: '2000000', spender, token: feeToken }],
+        }),
+      ).toThrow(Action.InvalidActionError)
+  })
+
+  test('rejects malformed provider token allowances', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [approveCall(1_000_000n), depositCall], type: 'evm:calls' },
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+        tokenApprovals: [{ amount: '0x10', spender, token: sourceToken }],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Routes.Action.InvalidActionError: Malformed token approval allowance.]`,
     )
   })
 
@@ -78,7 +129,7 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Approval spender must match a later prepared executor.]`,
+      `[Routes.Action.InvalidActionError: Approval spender must match a later prepared executor.]`,
     )
   })
 
@@ -93,7 +144,7 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Malformed approval calldata.]`,
+      `[Routes.Action.InvalidActionError: Malformed approval calldata.]`,
     )
   })
 
@@ -104,9 +155,7 @@ describe('validateEvmCalls', () => {
         sourceAmount: '1000000',
         sourceTokenAddress: sourceToken,
       }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Malformed EVM calls.]`,
-    )
+    ).toThrowErrorMatchingInlineSnapshot(`[Routes.Action.InvalidActionError: Malformed EVM calls.]`)
   })
 
   test('rejects unsupported source token calls', () => {
@@ -120,7 +169,7 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Unsupported source token call.]`,
+      `[Routes.Action.InvalidActionError: Unsupported source token call.]`,
     )
   })
 
@@ -132,7 +181,7 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Native value must match a validated provider fee.]`,
+      `[Routes.Action.InvalidActionError: Native value must match a validated provider fee.]`,
     )
   })
 
@@ -157,7 +206,7 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Malformed native value allowance.]`,
+      `[Routes.Action.InvalidActionError: Malformed native value allowance.]`,
     )
   })
 

package/src/internal/{funding → routes}/Action.ts

@@ -4,14 +4,14 @@ import * as z from 'zod/mini'
 import * as OpenApi from '../OpenApi.js'
 
 /**
- * Executable source-chain actions returned by funding transfer creation. A
+ * Executable source-chain actions returned by route transfer creation. A
  * strict discriminated union: transfer reads never include an action.
  */
 
 const approve = AbiFunction.from('function approve(address spender, uint256 amount)')
 const approveSelector = AbiFunction.getSelector(approve)
 
-/** Zod schemas owned by funding actions. */
+/** Zod schemas owned by route actions. */
 export namespace schema {
   /** One unsigned EVM call, in the exchange quote API's call shape. */
   export const Call = OpenApi.component(
@@ -40,7 +40,7 @@ export namespace schema {
           ),
       })
       .check(z.describe('One unsigned EVM call.')),
-    'FundingActionCall',
+    'RoutesActionCall',
   )
 
   /** Ordered unsigned EVM calls the caller signs and submits on the source chain. */
@@ -56,7 +56,7 @@ export namespace schema {
         type: z.literal('evm:calls').check(z.describe('Action kind.')),
       })
       .check(z.describe('Ordered unsigned EVM calls to sign and submit on the source chain.')),
-    'FundingEvmCallsAction',
+    'RoutesEvmCallsAction',
   )
 
   /** Executable source-chain action attached to a creation response. */
@@ -64,7 +64,7 @@ export namespace schema {
     z
       .discriminatedUnion('type', [EvmCalls])
       .check(z.describe('Executable source-chain action. Never returned by transfer reads.')),
-    'FundingAction',
+    'RoutesAction',
   )
 }
 
@@ -85,6 +85,16 @@ export type NativeValue = {
   value: string
 }
 
+/** One exact token approval independently validated by a route provider. */
+export type TokenApproval = {
+  /** Exact approval amount in token base units. */
+  amount: string
+  /** Contract allowed to spend the token. */
+  spender: string
+  /** Token contract carrying the approval. */
+  token: string
+}
+
 /**
  * Validates prepared EVM calls before persistence. Token calls, approval
  * targets, spenders, amounts, selectors, and native value must match the route.
@@ -98,6 +108,16 @@ export function validateEvmCalls(options: validateEvmCalls.Options): void {
       throw new InvalidActionError('Malformed native value allowance.')
     nativeValues.add(`${to.toLowerCase()}:${BigInt(value).toString()}`)
   }
+  const tokenApprovals = new Set<string>()
+  for (const { amount, spender, token } of options.tokenApprovals ?? []) {
+    if (
+      !/^\d+$/.test(amount) ||
+      !Address.validate(spender, { strict: false }) ||
+      !Address.validate(token, { strict: false })
+    )
+      throw new InvalidActionError('Malformed token approval allowance.')
+    tokenApprovals.add(`${token.toLowerCase()}:${spender.toLowerCase()}:${BigInt(amount)}`)
+  }
   for (const [index, call] of action.data.calls.entries()) {
     const callValue = BigInt(call.value)
     if (callValue > 0n && !nativeValues.has(`${call.to.toLowerCase()}:${callValue.toString()}`))
@@ -110,7 +130,6 @@ export function validateEvmCalls(options: validateEvmCalls.Options): void {
     if (targetsSourceToken && selector !== approveSelector)
       throw new InvalidActionError('Unsupported source token call.')
     if (selector !== approveSelector) continue
-    if (!targetsSourceToken) throw new InvalidActionError('Approval must target the source token.')
     if (call.data.length !== approveSelector.length + 128)
       throw new InvalidActionError('Malformed approval calldata.')
     const [spender, amount] = AbiFunction.decodeData(approve, call.data as Hex.Hex)
@@ -120,7 +139,13 @@ export function validateEvmCalls(options: validateEvmCalls.Options): void {
         .some((next) => Address.isEqual(next.to as Address.Address, spender))
     )
       throw new InvalidActionError('Approval spender must match a later prepared executor.')
-    if (amount >= Solidity.maxUint256 || amount > BigInt(options.sourceAmount))
+    const providerValidated = tokenApprovals.has(
+      `${call.to.toLowerCase()}:${spender.toLowerCase()}:${amount}`,
+    )
+    if (
+      amount >= Solidity.maxUint256 ||
+      (!providerValidated && (!targetsSourceToken || amount > BigInt(options.sourceAmount)))
+    )
       throw new InvalidActionError('Approval must stay bounded to the route amount.')
   }
 }
@@ -136,10 +161,12 @@ export declare namespace validateEvmCalls {
     sourceAmount: string
     /** Source token contract address. */
     sourceTokenAddress: string
+    /** Exact additional token approvals established by provider-specific validation. */
+    tokenApprovals?: readonly TokenApproval[] | undefined
   }
 }
 
 /** Error thrown when a provider returns an action outside the route's bounds. */
 export class InvalidActionError extends Error {
-  override name = 'Funding.Action.InvalidActionError'
+  override name = 'Routes.Action.InvalidActionError'
 }

package/src/internal/{funding → routes}/Catalog.test.ts

@@ -3,7 +3,7 @@ import type { Context } from 'hono'
 import * as TestApp from '../../../test/App.js'
 import type * as App from '../../App.js'
 import * as Db from '../../db/Db.js'
-import * as core_Catalog from '../../db/tables/fundingCatalog.js'
+import * as core_Catalog from '../../db/tables/routesCatalog.js'
 import * as Catalog from './Catalog.js'
 
 const data = {
@@ -142,7 +142,7 @@ describe('compile', () => {
         }),
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Catalog.InvalidCatalogError: Duplicate chain key "ETH".]`,
+      `[Routes.Catalog.InvalidCatalogError: Duplicate chain key "ETH".]`,
     )
   })
 
@@ -159,7 +159,7 @@ describe('compile', () => {
         }),
       ),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Catalog.InvalidCatalogError: Unknown route token "missing".]`,
+      `[Routes.Catalog.InvalidCatalogError: Unknown route token "missing".]`,
     )
   })