tapimo 0.8.0 → 0.9.0

package/src/apps/composition.test.ts

@@ -18,7 +18,12 @@ async function document(app: { request: (path: string) => Promise<Response> | Re
       string,
       Partial<Record<'get' | 'post', { operationId: string; tags?: readonly string[] | undefined }>>
     >
-    tags: readonly { description: string; name: string }[]
+    tags: readonly {
+      description: string
+      name: string
+      'x-displayName'?: string | undefined
+      'x-pagePath'?: string | undefined
+    }[]
     webhooks?: Record<string, unknown> | undefined
     'x-tagGroups'?: readonly { name: string; tags: readonly string[] }[] | undefined
   }
@@ -294,7 +299,6 @@ describe('funding()', () => {
         '/v1/funding/chains',
         '/v1/funding/deposit-addresses',
         '/v1/funding/deposit-addresses/{id}',
-        '/v1/funding/deposit-addresses/{id}/deposits',
         '/v1/funding/deposit-addresses/{id}/reconcile',
         '/v1/funding/deposits',
         '/v1/funding/deposits/{id}',
@@ -311,7 +315,7 @@ describe('funding()', () => {
     expect(spec['x-tagGroups']).toEqual([
       {
         name: 'Funding & Bridge API',
-        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Transfers'],
+        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Funding Transfers'],
       },
     ])
     expect(
@@ -325,13 +329,12 @@ describe('funding()', () => {
       'reconcileFundingDepositAddress',
       'getFundingDepositAddress',
       'getFundingDeposit',
-      'listFundingDepositAddressDeposits',
       'listFundingDeposits',
     ])
     expect((await app.request('/v1/tokens')).status).toBe(404)
   })
 
-  test('maps operations to five tags and reuses Transfers across groups', async () => {
+  test('keeps data and funding transfers separate with the same display name', async () => {
     const app = App.create({ auth: false, db: TestApp.database() })
       .route('/', data())
       .route('/', funding())
@@ -344,9 +347,10 @@ describe('funding()', () => {
     expect({
       chains: operationTag('/v1/funding/chains', 'get'),
       depositAddress: operationTag('/v1/funding/deposit-addresses', 'post'),
-      deposits: operationTag('/v1/funding/deposit-addresses/{id}/deposits', 'get'),
+      deposits: operationTag('/v1/funding/deposits', 'get'),
       providers: operationTag('/v1/funding/providers', 'get'),
       quotes: operationTag('/v1/funding/quotes', 'get'),
+      tokenTransfers: operationTag('/v1/transfers', 'get'),
       transfers: operationTag('/v1/funding/transfers', 'get'),
       vault: operationTag('/v1/funding/transfers/vault', 'post'),
       zone: operationTag('/v1/funding/transfers/zone', 'post'),
@@ -356,17 +360,42 @@ describe('funding()', () => {
       deposits: ['Deposit Addresses'],
       providers: ['Providers'],
       quotes: ['Quotes'],
-      transfers: ['Transfers'],
-      vault: ['Transfers'],
-      zone: ['Transfers'],
+      tokenTransfers: ['Transfers'],
+      transfers: ['Funding Transfers'],
+      vault: ['Funding Transfers'],
+      zone: ['Funding Transfers'],
     })
 
     const groups = Object.fromEntries(
       (spec['x-tagGroups'] ?? []).map((group) => [group.name, group.tags]),
     )
     expect(groups['Data API']).toContain('Transfers')
-    expect(groups['Funding & Bridge API']).toContain('Transfers')
+    expect(groups['Data API']).not.toContain('Funding Transfers')
+    expect(groups['Funding & Bridge API']).toContain('Funding Transfers')
+    expect(groups['Funding & Bridge API']).not.toContain('Transfers')
     expect(spec.tags.filter((tag) => tag.name === 'Transfers')).toHaveLength(1)
+    expect(spec.tags.filter((tag) => tag.name === 'Funding Transfers')).toEqual([
+      {
+        description: 'Inbound funding transfers.',
+        name: 'Funding Transfers',
+        'x-displayName': 'Transfers',
+        'x-pagePath': 'funding/transfers',
+      },
+    ])
+    expect(
+      Object.fromEntries(
+        (groups['Funding & Bridge API'] ?? []).map((name) => {
+          const tag = spec.tags.find((tag) => tag.name === name)
+          return [tag?.['x-displayName'] ?? tag?.name, tag?.['x-pagePath']]
+        }),
+      ),
+    ).toEqual({
+      Chains: 'funding/chains',
+      'Deposit Addresses': 'funding/deposit-addresses',
+      Providers: 'funding/providers',
+      Quotes: 'funding/quotes',
+      Transfers: 'funding/transfers',
+    })
   })
 })
 

package/src/apps/data/routes/balances.test.ts

@@ -3,6 +3,7 @@
 import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
 import { Value as core_Value } from 'ox'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 import { Actions } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
@@ -469,3 +470,44 @@ describe('GET /addresses/:address/balances', () => {
     expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
   })
 })
+
+describe('GET /v1/addresses/:address/balances/:token', () => {
+  test('returns one live balance without indexed holder discovery', async () => {
+    const client = app()
+    const holder = await holderWithBalance
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: { address: holder, token: TestApp.tokenWithHolders },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.id).toBe(TestApp.tokenWithHolders)
+    expect(body.token.address).toBe(TestApp.tokenWithHolders)
+    expect(body.amount).toMatch(/^\d+$/)
+    expect(core_Value.from(body.formatted, body.decimals)).toBe(BigInt(body.amount))
+    expect(body.valuation).toEqual({ amount: body.formatted, currency: 'USD' })
+  })
+
+  test('returns zero for a token the account does not hold', async () => {
+    const client = app()
+    const response = await client.v1.addresses[':address'].balances[':token'].$get(
+      {
+        param: {
+          address: privateKeyToAccount(generatePrivateKey()).address,
+          token: TestApp.tokenWithHolders,
+        },
+        query: {},
+      },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalance.Response)
+
+    expect(response.status).toBe(200)
+    expect(body.amount).toBe('0')
+    expect(body.formatted).toBe('0')
+  })
+})

package/src/apps/data/routes/balances.ts

@@ -181,102 +181,235 @@ export namespace schema {
       })
       .check(z.describe('A page of TIP-20 token balances held by this account.'))
   }
+
+  /** Schemas for the getAddressBalance operation. */
+  export namespace getAddressBalance {
+    /** Path parameters for a single address balance request. */
+    export const Params = z
+      .object({
+        address: Schema.Address.check(
+          z.describe('The account address whose token balance you want to read.'),
+        ),
+        token: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address.')),
+      })
+      .check(z.describe('Path parameters for reading one account token balance.'))
+
+    /** Query parameters for a single address balance request. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        'valuation.currency': Schema.Denomination,
+      })
+      .check(z.describe('Query parameters for reading one account token balance.'))
+
+    /** A single TIP-20 token balance held by an address. */
+    export const Response = getAddressBalances.Balance.check(
+      z.describe('One TIP-20 token balance held by this account.'),
+    )
+  }
 }
 
 /**
  * Creates address-scoped balance handlers, mounted under the `/addresses`
- * composer. Exposes `GET /:address/balances`, the held-balance page.
+ * composer. Exposes the held-balance page and individual token balances.
  */
 export function addresses(options: addresses.Options = {}) {
   const oracle = options.fx?.oracle ?? FxOracle.ecb()
-  return new Hono<App.Environment>().get(
-    '/v1/addresses/:address/balances',
-    Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-    OpenApi.validate('param', schema.getAddressBalances.Params, {
-      code: 'address_invalid',
-      message: 'Invalid account address',
-    }),
-    OpenApi.validate('query', schema.getAddressBalances.Query, {
-      code: 'query_invalid',
-      message: 'Invalid query parameters',
-    }),
-    OpenApi.describeRoute({
-      description:
-        'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form, and each verified holding carries its nominal value in the requested denomination.',
-      operationId: 'getAddressBalances',
-      responses: OpenApi.responses({
-        errors: { 502: 'Could not read balance or token data from an upstream service.' },
-        success: {
-          description: 'A page of token balances for this account.',
-          schema: schema.getAddressBalances.Response,
-        },
+  return new Hono<App.Environment>()
+    .get(
+      '/v1/addresses/:address/balances',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getAddressBalances.Params, {
+        code: 'address_invalid',
+        message: 'Invalid account address',
       }),
-      summary: 'List address balances',
-      tags: ['Balances'],
-    }),
-    Cache.response<App.Environment>({
-      cacheControl: Cache.policies.noStore,
-      name: 'tempo-api:addresses:v1',
-      key: (c) => Cache.urlKey(c, schema.getAddressBalances.Query),
-    }),
-    async (c) => {
-      if (Auth.narrowAccess) return Auth.paidAccessError(c)
-      if (OpenApi.narrowValidation)
-        return OpenApi.validationError(c, {
-          code: 'address_invalid',
-          message: 'Invalid request parameters',
-        })
-      if (OpenApi.narrowValidation)
-        return OpenApi.validationError(c, {
-          code: 'query_invalid',
-          message: 'Invalid request parameters',
-        })
-
-      const { address } = c.req.valid('param')
-      const query = c.req.valid('query')
+      OpenApi.validate('query', schema.getAddressBalances.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Lists how much of each TIP-20 token an account holds, ordered from largest to smallest balance. Amounts are returned in raw base units and human-readable form, and each verified holding carries its nominal value in the requested denomination.',
+        operationId: 'getAddressBalances',
+        responses: OpenApi.responses({
+          errors: { 502: 'Could not read balance or token data from an upstream service.' },
+          success: {
+            description: 'A page of token balances for this account.',
+            schema: schema.getAddressBalances.Response,
+          },
+        }),
+        summary: 'List address balances',
+        tags: ['Balances'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:addresses:v1',
+        key: (c) => Cache.urlKey(c, schema.getAddressBalances.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'address_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid request parameters',
+          })
+
+        const { address } = c.req.valid('param')
+        const query = c.req.valid('query')
 
-      try {
+        try {
+          const chainId = query.chainId ?? c.get('chainId')
+          // `currency` only makes sense against verified tokens, so it implies
+          // `verified=true` from the caller's perspective.
+          const verified = query.verified || query.currency !== undefined
+          const feeEligible = query.feeEligible ?? false
+
+          // The fee-token set powers both the per-row `feeEligible` flag (always)
+          // and the optional `feeEligible=true` page restriction. It is memoized
+          // per chain (a near-constant), so one read feeds the page, the count,
+          // and the row enrichment. It is a best-effort enrichment: a lookup
+          // failure omits `feeEligible` rather than failing the page — unless the
+          // caller explicitly asked to filter by `feeEligible`, where the filter
+          // can't be honored, so the failure surfaces as the declared `502`.
+          const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
+            if (feeEligible) throw cause
+            return undefined
+          })
+
+          const balances = await getAddressBalances(c, {
+            address,
+            chainId,
+            currency: query.currency,
+            cursor: query.cursor,
+            denomination: query['valuation.currency'] ?? 'USD',
+            feeEligible,
+            feeTokens,
+            includeTotalCount: query.include.includes('totalCount'),
+            limit: query.limit,
+            oracle,
+            page: query.page,
+            verified,
+          })
+
+          return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
+        } catch (cause) {
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/addresses/:address/balances/:token',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getAddressBalance.Params, {
+        code: 'address_invalid',
+        message: 'Invalid address or token address',
+      }),
+      OpenApi.validate('query', schema.getAddressBalance.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Returns the live balance of one TIP-20 token held by an account, including token metadata and a human-readable amount.',
+        operationId: 'getAddressBalance',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              description: 'The token is not a registered TIP-20 token.',
+              codes: ['token_not_found'],
+            },
+            502: 'Could not read balance or token data from an upstream service.',
+          },
+          success: {
+            description: 'The requested token balance for this account.',
+            schema: schema.getAddressBalance.Response,
+          },
+        }),
+        summary: 'Get address balance',
+        tags: ['Balances'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        name: 'tempo-api:addresses:v1',
+        key: (c) => Cache.urlKey(c, schema.getAddressBalance.Query),
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'address_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid request parameters',
+          })
+
+        const { address, token } = c.req.valid('param')
+        const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
-        // `currency` only makes sense against verified tokens, so it implies
-        // `verified=true` from the caller's perspective.
-        const verified = query.verified || query.currency !== undefined
-        const feeEligible = query.feeEligible ?? false
-
-        // The fee-token set powers both the per-row `feeEligible` flag (always)
-        // and the optional `feeEligible=true` page restriction. It is memoized
-        // per chain (a near-constant), so one read feeds the page, the count,
-        // and the row enrichment. It is a best-effort enrichment: a lookup
-        // failure omits `feeEligible` rather than failing the page — unless the
-        // caller explicitly asked to filter by `feeEligible`, where the filter
-        // can't be honored, so the failure surfaces as the declared `502`.
-        const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch((cause) => {
-          if (feeEligible) throw cause
-          return undefined
-        })
-
-        const balances = await getAddressBalances(c, {
-          address,
-          chainId,
-          currency: query.currency,
-          cursor: query.cursor,
-          denomination: query['valuation.currency'] ?? 'USD',
-          feeEligible,
-          feeTokens,
-          includeTotalCount: query.include.includes('totalCount'),
-          limit: query.limit,
-          oracle,
-          page: query.page,
-          verified,
-        })
 
-        return c.json(Response.validated(schema.getAddressBalances.Response, balances), 200)
-      } catch (cause) {
-        if (cause instanceof Valuation.UnsupportedDenominationError)
-          return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
-        return Response.upstream(c, cause)
-      }
-    },
-  )
+        try {
+          const snapshot = await VerifiedTokens.snapshot(c, chainId)
+          const [balance, resolvedToken] = await Promise.all([
+            Timing.time(c, 'balance_rpc', async () => {
+              const result = await Actions.token.getBalance(c.get('getClient')(chainId), {
+                account: address,
+                token,
+              })
+              return result.amount
+            }),
+            Timing.time(c, 'token', () =>
+              Tokens.resolveToken(c, { address: token, chainId, include: [], snapshot }),
+            ),
+          ])
+          const denomination = query['valuation.currency'] ?? 'USD'
+          const rates = await Valuation.ratesFor(c, {
+            currencies: snapshot.byAddress.has(token) ? [resolvedToken.currency] : [],
+            denomination,
+            oracle,
+          })
+          const feeTokens = await FeeAmm.feeTokenSet(c, chainId).catch(() => undefined)
+
+          return c.json(
+            Response.validated(schema.getAddressBalance.Response, {
+              amount: balance.toString(),
+              currency: resolvedToken.currency,
+              decimals: resolvedToken.decimals,
+              ...(feeTokens ? { feeEligible: feeTokens.has(token) } : {}),
+              formatted: core_Value.format(balance, resolvedToken.decimals),
+              id: token,
+              token: resolvedToken,
+              valuation: Valuation.valuationFor({
+                amount: balance,
+                denomination,
+                rates,
+                token: snapshot.byAddress.get(token),
+              }),
+            }),
+            200,
+          )
+        } catch (cause) {
+          if (Tokens.isTokenNotFound(cause))
+            return Response.error(c, {
+              code: 'token_not_found',
+              message: 'Token not found',
+              status: 404,
+            })
+          if (cause instanceof Valuation.UnsupportedDenominationError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
 }
 
 export declare namespace addresses {

package/src/apps/data/routes/earn.test.ts

@@ -28,6 +28,7 @@ type OpenApiDocument = {
     string,
     {
       get?: {
+        description?: string
         parameters?: readonly {
           description?: string
           name?: string
@@ -109,12 +110,6 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         period: 'active',
         status: 'complete',
       }).success,
-      lifetime: Earn.schema.getEarnVaultEarnings.Response.safeParse({
-        ...response,
-        lifetimeEarnings: '0',
-        period: 'lifetime',
-        status: 'complete',
-      }).success,
       completeWithoutEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
         period: 'lifetime',
@@ -125,12 +120,23 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         period: 'active',
         status: 'incomplete_cost_basis',
       }).success,
+      incompleteWindow: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        period: '30d',
+        status: 'incomplete_cost_basis',
+      }).success,
       incompleteWithEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
         lifetimeEarnings: '0',
         period: 'lifetime',
         status: 'incomplete_cost_basis',
       }).success,
+      lifetime: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        lifetimeEarnings: '0',
+        period: 'lifetime',
+        status: 'complete',
+      }).success,
       pending: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
         period: 'lifetime',
@@ -141,34 +147,77 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         period: 'active',
         status: 'pending_redemption',
       }).success,
+      pendingWindow: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        period: '30d',
+        status: 'pending_redemption',
+      }).success,
       pendingWithEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
         lifetimeEarnings: '0',
         period: 'lifetime',
         status: 'pending_redemption',
       }).success,
+      window: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        period: '30d',
+        status: 'complete',
+        windowEarnings: '0',
+      }).success,
+      windowWithActiveEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        activeEarnings: '0',
+        period: '30d',
+        status: 'complete',
+      }).success,
+      windowWithoutEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        period: '30d',
+        status: 'complete',
+      }).success,
     }).toMatchInlineSnapshot(`
       {
         "active": true,
         "activeWithLifetimeEarnings": false,
         "completeWithoutEarnings": false,
         "incomplete": true,
+        "incompleteWindow": true,
         "incompleteWithEarnings": false,
         "lifetime": true,
         "pending": true,
         "pendingActive": false,
+        "pendingWindow": true,
         "pendingWithEarnings": false,
+        "window": true,
+        "windowWithActiveEarnings": false,
+        "windowWithoutEarnings": false,
       }
     `)
   })
 })
 
 describe('schema.getEarnVaultEarnings.Query', () => {
-  test('defaults to lifetime and accepts active earnings', () => {
+  test('defaults to lifetime and accepts active and trailing earnings', () => {
     expect([
       Earn.schema.getEarnVaultEarnings.Query.parse({}).period,
+      Earn.schema.getEarnVaultEarnings.Query.parse({ period: '30d' }).period,
       Earn.schema.getEarnVaultEarnings.Query.parse({ period: 'active' }).period,
-    ]).toStrictEqual(['lifetime', 'active'])
+    ]).toStrictEqual(['lifetime', '30d', 'active'])
+  })
+})
+
+describe('calculateWindowEarnings', () => {
+  test('adjusts snapshot growth for deposits and realized assets', () => {
+    expect(
+      Earn.calculateWindowEarnings({
+        deposited: 50n,
+        endingValue: 130n,
+        finalized: 10n,
+        openingValue: 100n,
+        redeemed: 15n,
+        withdrewExact: 5n,
+      }),
+    ).toBe(10n)
   })
 })
 
@@ -1098,6 +1147,30 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
     60_000,
   )
 
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns cash-flow-adjusted trailing earnings',
+    async () => {
+      const app = TestApp.create({ auth: false, cache })
+      const response = await app.request(
+        `/v1/earn/vaults/${TestEarn.activeEarningsVaultAddress}/earnings/${TestEarn.activeEarningsAddress}?chainId=${TestEarn.chain.id}&period=30d`,
+      )
+
+      expect(response.status).toBe(200)
+      const earnings = await TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+      if (earnings.status !== 'complete' || earnings.period !== '30d')
+        throw new Error('Expected complete trailing earnings history.')
+      expect(earnings).toMatchObject({
+        account: TestEarn.activeEarningsAddress,
+        period: '30d',
+        status: 'complete',
+        windowEarnings: expect.stringMatching(/^-?\d+$/),
+      })
+      expect(earnings).not.toHaveProperty('activeEarnings')
+      expect(earnings).not.toHaveProperty('lifetimeEarnings')
+    },
+    60_000,
+  )
+
   test.runIf(Runtime.get().mode === 'testnet')(
     'omits lifetime earnings when venue shares make the cost basis incomplete',
     async () => {
@@ -1377,14 +1450,21 @@ describe('OpenAPI', () => {
     const app = TestApp.create({ auth: false, cache })
     const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
     const operation = spec.paths['/v1/earn/vaults/{vaultId}/earnings/{address}']?.get
+    const period = operation?.parameters?.find((parameter) => parameter.name === 'period')
     const response = JSON.stringify(operation?.responses)
 
+    expect(operation?.description).toContain('the trailing 30 days')
+    expect(period?.description).toContain('trailing 30 days')
+    expect(period?.schema?.enum).toStrictEqual(['30d', 'active', 'lifetime'])
+    expect(period?.schema?.examples).toStrictEqual(['lifetime'])
     expect(response).toContain('"earn_vault_not_found"')
     expect(response).toContain('Stable resource ID for these vault earnings')
     expect(response).toContain('Current share value plus completed redemptions')
     expect(response).toContain('weighted-average asset cost basis')
-    expect(response).toContain('cannot reconstruct the remaining asset cost basis')
+    expect(response).toContain('Ending share value plus realized assets')
+    expect(response).toContain('cannot reconstruct the asset cost basis for the requested period')
     expect(response).toContain('"active"')
+    expect(response).toContain('"30d"')
     expect(response).toContain('"incomplete_cost_basis"')
     expect(response).toContain('"pending_redemption"')
   })