tapimo 0.7.2 → 0.9.0

package/src/internal/funding/SourceObservation.test.ts

@@ -0,0 +1,301 @@
+import * as NodeBuffer from 'node:buffer'
+
+import { AbiEvent } from 'ox'
+
+import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as TestRelay from '../../../test/Relay.js'
+import * as DepositAddress from './DepositAddress.js'
+import * as Reconciliation from './Reconciliation.js'
+import * as SourceObservation from './SourceObservation.js'
+import * as Relay from './providers/relay.js'
+
+const transferEvent = AbiEvent.from(
+  'event Transfer(address indexed from, address indexed to, uint256 value)',
+)
+
+describe('scan', () => {
+  test('finds confirmed transfers into active routes', async () => {
+    const route = TestFunding.transferSnapshot()
+    const address = `0x${'44'.repeat(20)}`
+    const sender = `0x${'55'.repeat(20)}`
+    const transactionHash = `0x${'aa'.repeat(32)}`
+    const requests: unknown[] = []
+    const server = await TestRelay.createServer(async (request, response) => {
+      const chunks: Uint8Array[] = []
+      for await (const chunk of request) chunks.push(chunk)
+      const body = JSON.parse(NodeBuffer.Buffer.concat(chunks).toString()) as {
+        id: number
+        method: string
+      }
+      requests.push(body)
+      const result =
+        body.method === 'eth_blockNumber'
+          ? '0x10'
+          : [
+              {
+                address: route.sourceToken.address,
+                blockHash: `0x${'bb'.repeat(32)}`,
+                blockNumber: '0x10',
+                data: `0x${1_000_000n.toString(16).padStart(64, '0')}`,
+                logIndex: '0x2',
+                removed: false,
+                topics: [
+                  AbiEvent.getSelector(transferEvent),
+                  topicAddress(sender),
+                  topicAddress(address),
+                ],
+                transactionHash,
+                transactionIndex: '0x0',
+              },
+            ]
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ id: body.id, jsonrpc: '2.0', result }))
+    })
+
+    try {
+      const result = await SourceObservation.scan({
+        chainId: route.sourceChain.id,
+        routes: [{ address, id: 'fda_source_observation' }],
+        rpcUrls: [server.url],
+        tokenAddress: route.sourceToken.address,
+      })
+
+      expect({ requests, result }).toMatchInlineSnapshot(`
+        {
+          "requests": [
+            {
+              "id": 0,
+              "jsonrpc": "2.0",
+              "method": "eth_blockNumber",
+            },
+            {
+              "id": 1,
+              "jsonrpc": "2.0",
+              "method": "eth_getLogs",
+              "params": [
+                {
+                  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                  "fromBlock": "0x1",
+                  "toBlock": "0x10",
+                  "topics": [
+                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+                    null,
+                    [
+                      "0x0000000000000000000000004444444444444444444444444444444444444444",
+                    ],
+                  ],
+                },
+              ],
+            },
+          ],
+          "result": {
+            "cursor": 16n,
+            "head": 16n,
+            "observations": [
+              {
+                "addressId": "fda_source_observation",
+                "amount": "1000000",
+                "blockNumber": 16n,
+                "chainId": "eip155:8453",
+                "sender": "0x5555555555555555555555555555555555555555",
+                "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+                "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "transferIndex": 2,
+              },
+            ],
+          },
+        }
+      `)
+    } finally {
+      await server.closeAsync()
+    }
+  })
+})
+
+describe('observe', () => {
+  test('creates one chain-detected deposit and attaches the Relay request later', async () => {
+    const database = TestApp.databaseFactory()
+    const route = TestFunding.transferSnapshot()
+    const providerAddress = `0x${'44'.repeat(20)}`
+    const sender = `0x${'55'.repeat(20)}`
+    const sourceTransactionHash = `0x${'aa'.repeat(32)}`
+    const address = await DepositAddress.create(database(), {
+      apiKeyId: 'key_source_observation',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      id: 'fda_source_observation',
+      now: new Date('2026-01-01T00:00:00.000Z'),
+      orgId: 'org_source_observation',
+      providerOutputToken: route.destinationToken,
+      snapshot: {
+        address: providerAddress,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        provider: route.provider,
+        recipient: route.recipient,
+        refundAddress: `0x${'66'.repeat(20)}`,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+        subsidize: false,
+      },
+    })
+    const input = {
+      addressId: address.id,
+      amount: '1000000',
+      chainId: route.sourceChain.id,
+      now: new Date('2026-01-01T00:00:01.000Z'),
+      recipient: providerAddress,
+      sender,
+      tokenAddress: route.sourceToken.address,
+      transactionHash: sourceTransactionHash,
+      transferIndex: 2,
+    }
+    const [first, second] = await Promise.all([
+      SourceObservation.observe(database(), input),
+      SourceObservation.observe(database(), input),
+    ])
+    const routes = await SourceObservation.listRoutes(database(), {
+      providerId: 'relay',
+      sourceChainId: route.sourceChain.id,
+      sourceTokenKey: route.sourceToken.tokenKey,
+    })
+    const server = await TestRelay.createServer((request, response) => {
+      request.resume()
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ requests: [] }))
+    })
+    const dispatches: Parameters<Reconciliation.createTracker.Options['dispatch']>[] = []
+
+    try {
+      const tracker = Reconciliation.createTracker({
+        db: database,
+        dispatch: async (...parameters) => {
+          dispatches.push(parameters)
+        },
+        providers: [Relay.relay({ apiKey: 'relay-api-key', baseUrl: server.url })],
+        verifyTransfers: async () => [],
+      })
+      const pending = await tracker.reconcile({
+        addressId: address.id,
+        trigger: 'chain',
+        type: 'funding:deposit-address:reconcile',
+      })
+      const reconciled = await Reconciliation.reconcileRequest(database(), {
+        address,
+        request: {
+          createdAt: '2026-01-01T00:00:02.000Z',
+          destinationTransactionHashes: [],
+          id: 'relay-source-request',
+          sourceTransactionHashes: [sourceTransactionHash],
+          status: 'pending',
+          updatedAt: '2026-01-01T00:00:03.000Z',
+        },
+        trigger: 'chain',
+        verifyTransfers: async () => [
+          {
+            amount: '1000000',
+            sender,
+            transactionHash: sourceTransactionHash,
+            transferIndex: 2,
+          },
+        ],
+      })
+      const [record] = await FundingDeposits.listBySourceTransaction(database(), {
+        depositAddressId: address.id,
+        sourceTransactionHash,
+      })
+
+      expect({
+        dispatches,
+        outcomes: [first.type, second.type].toSorted(),
+        pending,
+        reconciled,
+        record: record
+          ? {
+              detectionTrigger: record.detectionTrigger,
+              providerRequestId: record.providerRequestId,
+              providerRequestIds: record.providerRequestIds,
+              providerTransferIndex: record.providerTransferIndex,
+              sourceAmount: record.snapshot.sourceAmount,
+              sourceTransferIndex: record.sourceTransferIndex,
+              status: record.status,
+            }
+          : undefined,
+        routes,
+        sameDeposit: (() => {
+          if (first.type === 'ignored' || second.type === 'ignored') return false
+          return first.record.id === second.record.id
+        })(),
+      }).toMatchInlineSnapshot(
+        {
+          dispatches: [[{ addressId: expect.any(String) }, { delaySeconds: 1 }]],
+        },
+        `
+        {
+          "dispatches": [
+            [
+              {
+                "addressId": Any<String>,
+                "followUp": {
+                  "attempt": 0,
+                  "kind": "provider",
+                },
+                "trigger": "chain",
+                "type": "funding:deposit-address:reconcile",
+              },
+              {
+                "delaySeconds": 1,
+              },
+            ],
+          ],
+          "outcomes": [
+            "created",
+            "existing",
+          ],
+          "pending": {
+            "created": 0,
+            "type": "completed",
+            "updated": 0,
+          },
+          "reconciled": {
+            "created": 0,
+            "terminal": false,
+            "updated": 1,
+          },
+          "record": {
+            "detectionTrigger": "chain",
+            "providerRequestId": "relay-source-request",
+            "providerRequestIds": [
+              "relay-source-request",
+            ],
+            "providerTransferIndex": 0,
+            "sourceAmount": {
+              "baseUnits": "1000000",
+              "currency": "USD",
+              "decimals": 6,
+              "formatted": "1",
+            },
+            "sourceTransferIndex": 2,
+            "status": "bridging",
+          },
+          "routes": [
+            {
+              "address": "0x4444444444444444444444444444444444444444",
+              "id": "fda_source_observation",
+            },
+          ],
+          "sameDeposit": true,
+        }
+      `,
+      )
+    } finally {
+      await server.closeAsync()
+    }
+  })
+})
+
+function topicAddress(address: string) {
+  return `0x${address.slice(2).toLowerCase().padStart(64, '0')}`
+}

package/src/internal/funding/SourceObservation.ts

@@ -0,0 +1,267 @@
+import { AbiEvent, Address, RpcTransport } from 'ox'
+import { createClient, custom, fallback } from 'viem'
+import { getBlockNumber, getLogs } from 'viem/actions'
+
+import type * as Db from '../../db/Db.js'
+import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
+import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as Value from '../Value.js'
+import * as Deposit from './Deposit.js'
+
+const addressBatchSize = 50
+const defaultBackfillBlocks = 16n
+const defaultConfirmations = 1
+const defaultMaximumBlocks = 16n
+const transferEvent = AbiEvent.from(
+  'event Transfer(address indexed from, address indexed to, uint256 value)',
+)
+
+/** Active reusable address watched by one chain-and-token observer shard. */
+export type Route = {
+  /** Provider-owned reusable address. */
+  address: string
+  /** Funding deposit address id. */
+  id: string
+}
+
+/** Verified source transfer discovered directly from an EVM log. */
+export type Observation = {
+  /** Funding deposit address that received the transfer. */
+  addressId: string
+  /** Source token quantity in base units. */
+  amount: string
+  /** Confirmed source block containing the transfer. */
+  blockNumber: bigint
+  /** Source chain CAIP-2 id. */
+  chainId: string
+  /** Source-chain sender. */
+  sender: string
+  /** Source token contract. */
+  tokenAddress: string
+  /** Source transaction hash. */
+  transactionHash: string
+  /** Transfer log position within the source transaction. */
+  transferIndex: number
+}
+
+/** Scans confirmed EVM blocks for transfers into active reusable addresses. */
+export async function scan(options: scan.Options): Promise<scan.Result> {
+  if (options.routes.length === 0)
+    return { cursor: options.cursor ?? 0n, head: options.cursor ?? 0n, observations: [] }
+  if (!Address.validate(options.tokenAddress, { strict: false }))
+    throw new ConfigurationError('source token address')
+  if (options.rpcUrls.length === 0) throw new ConfigurationError('source RPC URL')
+
+  const client = createClient({
+    transport: fallback(
+      options.rpcUrls.map((url) => {
+        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch ?? globalThis.fetch })
+        return custom(transport, { retryCount: 0 })
+      }),
+    ),
+  })
+  const head = await getBlockNumber(client, { cacheTime: 0 })
+  const confirmations = BigInt(options.confirmations ?? defaultConfirmations)
+  const confirmed = head >= confirmations ? head - confirmations + 1n : 0n
+  const backfillBlocks = options.backfillBlocks ?? defaultBackfillBlocks
+  const fromBlock = (() => {
+    if (options.cursor !== undefined) return options.cursor + 1n
+    if (confirmed >= backfillBlocks) return confirmed - backfillBlocks + 1n
+    return 0n
+  })()
+  if (fromBlock > confirmed)
+    return { cursor: options.cursor ?? confirmed, head: confirmed, observations: [] }
+  const maximumBlocks = options.maximumBlocks ?? defaultMaximumBlocks
+  const toBlock = minimum(confirmed, fromBlock + maximumBlocks - 1n)
+  const routesByAddress = new Map(
+    options.routes.map((route) => {
+      if (!Address.validate(route.address, { strict: false }))
+        throw new ConfigurationError('deposit address')
+      return [route.address.toLowerCase(), route] as const
+    }),
+  )
+  const addresses = [...routesByAddress.keys()] as Address.Address[]
+  const observations: Observation[] = []
+  for (let index = 0; index < addresses.length; index += addressBatchSize) {
+    const batch = addresses.slice(index, index + addressBatchSize)
+    const logs = await getLogs(client, {
+      address: options.tokenAddress as Address.Address,
+      args: { to: batch },
+      event: transferEvent,
+      fromBlock,
+      strict: true,
+      toBlock,
+    })
+    for (const log of logs) {
+      if (log.blockNumber === null || log.logIndex === null || !log.transactionHash) continue
+      const event = (() => {
+        try {
+          return AbiEvent.decode(transferEvent, { data: log.data, topics: log.topics })
+        } catch {
+          return undefined
+        }
+      })()
+      const route = event ? routesByAddress.get(event.to.toLowerCase()) : undefined
+      if (!event || !route) continue
+      observations.push({
+        addressId: route.id,
+        amount: event.value.toString(),
+        blockNumber: log.blockNumber,
+        chainId: options.chainId,
+        sender: event.from.toLowerCase(),
+        tokenAddress: options.tokenAddress.toLowerCase(),
+        transactionHash: log.transactionHash,
+        transferIndex: log.logIndex,
+      })
+    }
+  }
+  observations.sort(
+    (left, right) =>
+      Number(left.blockNumber - right.blockNumber) || left.transferIndex - right.transferIndex,
+  )
+  return { cursor: toBlock, head: confirmed, observations }
+}
+
+export declare namespace scan {
+  /** EVM shard state and scan bounds. */
+  type Options = {
+    /** Initial confirmed-block backfill when no cursor exists. */
+    backfillBlocks?: bigint | undefined
+    /** Source chain CAIP-2 id. */
+    chainId: string
+    /** Required block confirmations. */
+    confirmations?: number | undefined
+    /** Last confirmed block processed by the shard. */
+    cursor?: bigint | undefined
+    /** Fetch implementation override. */
+    fetch?: typeof globalThis.fetch | undefined
+    /** Maximum confirmed blocks processed in one invocation. */
+    maximumBlocks?: bigint | undefined
+    /** Active reusable addresses in the shard. */
+    routes: readonly Route[]
+    /** Ordered source-chain RPC endpoints. */
+    rpcUrls: readonly string[]
+    /** Source token contract. */
+    tokenAddress: string
+  }
+
+  /** Confirmed cursor and verified transfers produced by one scan. */
+  type Result = {
+    /** Last confirmed block processed by the shard. */
+    cursor: bigint
+    /** Latest block satisfying the confirmation policy. */
+    head: bigint
+    /** Verified transfers into active addresses. */
+    observations: readonly Observation[]
+  }
+}
+
+/** Lists the active Relay addresses assigned to one source observer shard. */
+export async function listRoutes(
+  db: Db.Db,
+  options: listRoutes.Options,
+): Promise<readonly Route[]> {
+  const records = await FundingDepositAddresses.listActiveSources(db, options)
+  return records.map((record) => ({ address: record.address, id: record.id }))
+}
+
+export declare namespace listRoutes {
+  /** Provider and source asset identifying one observer shard. */
+  type Options = {
+    /** Funding provider that owns the deposit addresses. */
+    providerId: string
+    /** Source chain CAIP-2 id. */
+    sourceChainId: string
+    /** Source token key. */
+    sourceTokenKey: string
+  }
+}
+
+/** Persists one verified source transfer before provider indexing. */
+export async function observe(db: Db.Db, input: observe.Input): Promise<observe.Result> {
+  const address = await FundingDepositAddresses.get(db, input.addressId)
+  if (
+    !address ||
+    address.providerId !== 'relay' ||
+    address.status !== 'active' ||
+    address.snapshot.sourceChain.id !== input.chainId ||
+    !Address.isEqual(
+      address.snapshot.sourceToken.address as Address.Address,
+      input.tokenAddress as Address.Address,
+    ) ||
+    !Address.isEqual(address.address as Address.Address, input.recipient as Address.Address)
+  )
+    return { type: 'ignored' }
+
+  return FundingDeposits.withSourceTransaction(db, {
+    depositAddressId: address.id,
+    fn: async (tx) => {
+      const existing = await FundingDeposits.listBySourceTransaction(tx, {
+        depositAddressId: address.id,
+        sourceTransactionHash: input.transactionHash,
+      })
+      const record =
+        existing.find((candidate) => candidate.sourceTransferIndex === input.transferIndex) ??
+        existing.find((candidate) => candidate.sourceTransferIndex === null)
+      if (record) return { record, type: 'existing' as const }
+      return Deposit.createFromSource(tx, {
+        now: input.now,
+        snapshot: {
+          ...address.snapshot,
+          depositAddressId: address.id,
+          sender: input.sender,
+          sourceAmount: Value.tokenAmount({
+            baseUnits: input.amount,
+            currency: address.snapshot.sourceToken.currency,
+            decimals: address.snapshot.sourceToken.decimals,
+          }),
+          sourceTransactionHashes: [input.transactionHash],
+        },
+        sourceTransactionHash: input.transactionHash,
+        sourceTransferIndex: input.transferIndex,
+      })
+    },
+    sourceTransactionHash: input.transactionHash,
+  })
+}
+
+export declare namespace observe {
+  /** Verified source transfer and route identity. */
+  type Input = {
+    /** Funding deposit address id. */
+    addressId: string
+    /** Source token quantity in base units. */
+    amount: string
+    /** Source chain CAIP-2 id. */
+    chainId: string
+    /** Detection time override. */
+    now?: Date | undefined
+    /** Provider-owned reusable address that received the transfer. */
+    recipient: string
+    /** Source-chain sender. */
+    sender: string
+    /** Source token contract. */
+    tokenAddress: string
+    /** Source transaction hash. */
+    transactionHash: string
+    /** Transfer log position within the source transaction. */
+    transferIndex: number
+  }
+
+  /** Persistence outcome for one chain-observed source transfer. */
+  type Result =
+    | { record: FundingDeposits.Record; type: 'created' | 'existing' }
+    | { type: 'ignored' }
+}
+
+function minimum(left: bigint, right: bigint) {
+  return left < right ? left : right
+}
+
+class ConfigurationError extends Error {
+  override name = 'FundingSourceObservation.ConfigurationError'
+
+  constructor(field: string) {
+    super(`Invalid ${field} configured for funding source observation.`)
+  }
+}

package/src/internal/funding/Subsidy.ts

@@ -129,7 +129,7 @@ export declare namespace Settler {
   }
 }
 
-/** Creates a subsidy settler backed by one dedicated pathUSD account. */
+/** Creates a subsidy settler backed by a Tempo account that holds pathUSD. */
 export function create(options: create.Options): Settler {
   const client = options.getClient()
   return {
@@ -225,7 +225,7 @@ export function create(options: create.Options): Settler {
 export declare namespace create {
   /** Dependencies and policy for one subsidy settler. */
   type Options = {
-    /** Dedicated account that signs subsidies and holds pathUSD. */
+    /** Tempo account that signs subsidies and holds pathUSD. */
     account: LocalAccount
     /** Trusted Tempo RPC client resolver. */
     getClient: Viem.GetClient

package/src/internal/funding/index.test.ts

@@ -12,6 +12,7 @@ test('exports funding modules', () => {
       "Provider",
       "Reconciliation",
       "Route",
+      "SourceObservation",
       "Subsidy",
       "Token",
       "Transfer",

package/src/internal/funding/index.ts

@@ -7,6 +7,7 @@ export * as Evidence from './Evidence.js'
 export * as Provider from './Provider.js'
 export * as Reconciliation from './Reconciliation.js'
 export * as Route from './Route.js'
+export * as SourceObservation from './SourceObservation.js'
 export * as Subsidy from './Subsidy.js'
 export * as Token from './Token.js'
 export * as Transfer from './Transfer.js'