tapimo 0.7.2 → 0.9.0

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

@@ -28,6 +28,7 @@ type OpenApiDocument = {
     string,
     {
       get?: {
+        description?: string
         parameters?: readonly {
           description?: string
           name?: string
@@ -87,6 +88,214 @@ describe('schema.getEarnVaults.Query', () => {
   })
 })
 
+describe('schema.getEarnVaultEarnings.Response', () => {
+  test('enforces status-specific earnings fields', () => {
+    const response = {
+      account: TestEarn.earningsAddress,
+      assetToken: TestEarn.assetTokenAddress,
+      currentValue: '1000000',
+      id: TestEarn.earningsAddress,
+    }
+
+    expect({
+      active: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        activeEarnings: '0',
+        period: 'active',
+        status: 'complete',
+      }).success,
+      activeWithLifetimeEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        lifetimeEarnings: '0',
+        period: 'active',
+        status: 'complete',
+      }).success,
+      completeWithoutEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...response,
+        period: 'lifetime',
+        status: 'complete',
+      }).success,
+      incomplete: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...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',
+        status: 'pending_redemption',
+      }).success,
+      pendingActive: Earn.schema.getEarnVaultEarnings.Response.safeParse({
+        ...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 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', '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)
+  })
+})
+
+describe('calculateActiveCostBasis', () => {
+  test('allocates weighted-average basis across partial exits', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { assets: 100n, kind: 'deposit', shares: 100n },
+          { assets: 300n, kind: 'deposit', shares: 100n },
+          { kind: 'redeem', shares: 100n },
+        ],
+        shareBalance: 100n,
+      }),
+    ).toBe(200n)
+  })
+
+  test('calculates remaining basis while an async redemption is pending', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { assets: 100n, kind: 'deposit', shares: 100n },
+          { kind: 'request', requestId: 'request-1', shares: 40n },
+        ],
+        shareBalance: 60n,
+      }),
+    ).toBe(60n)
+  })
+
+  test('restores removed basis when an async redemption is cancelled', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { assets: 100n, kind: 'deposit', shares: 100n },
+          { kind: 'request', requestId: 'request-1', shares: 40n },
+          { kind: 'cancel', requestId: 'request-1', shares: 40n },
+        ],
+        shareBalance: 100n,
+      }),
+    ).toBe(100n)
+  })
+
+  test('recovers after unknown-basis shares fully exit', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { kind: 'unknown', shares: 100n },
+          { kind: 'redeem', shares: 100n },
+          { assets: 200n, kind: 'deposit', shares: 100n },
+        ],
+        shareBalance: 100n,
+      }),
+    ).toBe(200n)
+  })
+
+  test('rejects remaining shares with unknown cost basis', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { assets: 100n, kind: 'deposit', shares: 100n },
+          { kind: 'unknown', shares: 100n },
+          { kind: 'redeem', shares: 100n },
+        ],
+        shareBalance: 100n,
+      }),
+    ).toBeUndefined()
+  })
+
+  test('rejects history that does not reconcile to the indexed share balance', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [{ assets: 100n, kind: 'deposit', shares: 100n }],
+        shareBalance: 99n,
+      }),
+    ).toBeUndefined()
+  })
+})
+
 describe('discoveryBatchLimit', () => {
   test('fetches one extra candidate without live filters', () => {
     expect(
@@ -864,6 +1073,136 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
   )
 })
 
+describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
+  test('returns chain selection errors', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const invalid = await app.request(
+      `/v1/earn/vaults/${TestEarn.vaultAddress}/earnings/${TestEarn.earningsAddress}?chainId=abc`,
+    )
+    const unsupported = await app.request(
+      `/v1/earn/vaults/${TestEarn.vaultAddress}/earnings/${TestEarn.earningsAddress}?chainId=999999`,
+    )
+
+    expect([
+      (await TestApp.json(invalid, Schema.ErrorResponse)).error.code,
+      (await TestApp.json(unsupported, Schema.ErrorResponse)).error.code,
+    ]).toStrictEqual(['chain_id_invalid', 'chain_id_unsupported'])
+  })
+
+  test('rejects malformed vault earnings parameters', async () => {
+    const response = await TestApp.create({ auth: false, cache }).request(
+      '/v1/earn/vaults/not-an-address/earnings/not-an-address',
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'earnings_invalid' },
+    })
+  })
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns lifetime return through indexed vault events',
+    async () => {
+      const app = TestApp.create({ auth: false, cache })
+      const response = await app.request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/earnings/${TestEarn.earningsAddress}?chainId=${TestEarn.chain.id}`,
+      )
+
+      expect(response.status).toBe(200)
+      const earnings = await TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+      if (earnings.status !== 'complete') throw new Error('Expected complete earnings history.')
+      expect(earnings).toMatchObject({
+        account: TestEarn.earningsAddress,
+        assetToken: TestEarn.assetTokenAddress,
+        currentValue: expect.stringMatching(/^\d+$/),
+        id: TestEarn.earningsAddress,
+        lifetimeEarnings: expect.stringMatching(/^-?\d+$/),
+        period: 'lifetime',
+        status: 'complete',
+      })
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns earnings on shares still held',
+    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=active`,
+      )
+
+      expect(response.status).toBe(200)
+      const earnings = await TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+      if (earnings.status !== 'complete' || earnings.period !== 'active')
+        throw new Error('Expected complete active earnings history.')
+      expect(earnings).toMatchObject({
+        account: TestEarn.activeEarningsAddress,
+        activeEarnings: expect.stringMatching(/^-?\d+$/),
+        period: 'active',
+        status: 'complete',
+      })
+      expect(earnings).not.toHaveProperty('lifetimeEarnings')
+    },
+    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 () => {
+      const app = TestApp.create({ auth: false, cache })
+      const response = await app.request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/earnings/${TestEarn.incompleteEarningsAddress}?chainId=${TestEarn.chain.id}`,
+      )
+
+      expect(response.status).toBe(200)
+      const earnings = await TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+      expect(earnings.status).toBe('incomplete_cost_basis')
+      expect(earnings).not.toHaveProperty('lifetimeEarnings')
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns not found for an address without an Earn vault',
+    async () => {
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/0x1111111111111111111111111111111111111111/earnings/${TestEarn.earningsAddress}?chainId=${TestEarn.chain.id}`,
+      )
+
+      expect(response.status).toBe(404)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'earn_vault_not_found' },
+      })
+    },
+    60_000,
+  )
+})
+
 describe('GET /v1/earn/vaults', () => {
   test.runIf(Runtime.get().mode === 'testnet')(
     'extracts an indexed deployment and applies onchain filters',
@@ -1039,6 +1378,7 @@ describe('OpenAPI', () => {
         '/v1/earn/vaults',
         '/v1/earn/vaults/verified',
         '/v1/earn/vaults/{vaultId}',
+        '/v1/earn/vaults/{vaultId}/earnings/{address}',
         '/v1/earn/vaults/{vaultId}/positions/{address}',
       ]),
     )
@@ -1105,4 +1445,27 @@ describe('OpenAPI', () => {
     expect(address?.schema?.examples).toStrictEqual([TestEarn.positionAddress])
     expect(vaultId?.schema?.examples).toStrictEqual([TestEarn.mainnetVaultAddress])
   })
+
+  test('documents vault-earnings variants', async () => {
+    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('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"')
+  })
 })