tapimo 0.7.1 → 0.8.0

package/src/internal/funding/DepositAddress.ts

@@ -0,0 +1,312 @@
+import * as z from 'zod/mini'
+
+import type * as Db from '../../db/Db.js'
+import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
+import * as Id from '../Id.js'
+import * as Provider from './Provider.js'
+import * as Transfer from './Transfer.js'
+
+/** Public funding deposit address statuses. */
+export const statuses = ['action-required', 'active'] as const
+
+/** Lifecycle status of a funding deposit address. */
+export type Status = (typeof statuses)[number]
+
+/** Internal responsibility for delivering the requested destination token. */
+export const deliveryStrategies = ['provider', 'tempo'] as const
+
+/** Whether the provider or Tempo delivers the requested destination token. */
+export type DeliveryStrategy = (typeof deliveryStrategies)[number]
+
+/** Bounded provider state retained privately for reconciliation. */
+export type ProviderState = Record<string, unknown>
+
+const transitions: Record<Status, readonly Status[]> = {
+  'action-required': ['active'],
+  active: ['action-required'],
+}
+
+/** Returns whether the lifecycle allows moving between address statuses. */
+export function canTransition(from: Status, to: Status): boolean {
+  return transitions[from].includes(to)
+}
+
+/** Generates a funding deposit address id (`fda_…`, lexically time-ordered). */
+export function generateId(now: Date = new Date()): string {
+  return Id.generateSortable('fda', now)
+}
+
+/** Zod schemas owned by the funding deposit address resource. */
+export namespace schema {
+  /** Funding deposit address lifecycle status. */
+  export const Status = z
+    .enum(statuses)
+    .check(
+      z.describe('Whether the address can safely process new deposits.'),
+      z.meta({ examples: ['active'] }),
+    )
+
+  /** Public fields persisted as the address snapshot. */
+  export const Snapshot = z
+    .object({
+      address: z
+        .string()
+        .check(
+          z.describe('Reusable source-chain deposit address.'),
+          z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
+        ),
+      destinationChain: Provider.schema.ChainRef,
+      destinationToken: Provider.schema.TokenRef,
+      provider: Provider.schema.ProviderRef,
+      recipient: z
+        .string()
+        .check(
+          z.regex(/^0x[0-9a-fA-F]{40}$/),
+          z.describe('Tempo account that receives completed deposits.'),
+          z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+        ),
+      refundAddress: z
+        .string()
+        .check(
+          z.describe('Source-chain address that receives refunds.'),
+          z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] }),
+        ),
+      sourceChain: Provider.schema.ChainRef,
+      sourceToken: Provider.schema.TokenRef,
+      subsidize: z
+        .boolean()
+        .check(
+          z.describe('Whether Tempo guarantees normalized 1:1 delivery.'),
+          z.meta({ examples: [false] }),
+        ),
+    })
+    .check(z.describe('Public route and ownership-independent fields of a deposit address.'))
+
+  /** One reusable funding deposit address. */
+  export const FundingDepositAddress = z
+    .object({
+      address: Snapshot.shape.address,
+      createdAt: z
+        .string()
+        .check(
+          z.describe('When the deposit address was created (ISO 8601).'),
+          z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
+        ),
+      destinationChain: Snapshot.shape.destinationChain,
+      destinationToken: Snapshot.shape.destinationToken,
+      id: z
+        .string()
+        .check(
+          z.regex(/^fda_[A-Za-z0-9_-]+$/),
+          z.describe('Funding deposit address id (`fda_…`).'),
+          z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+        ),
+      provider: Snapshot.shape.provider,
+      recipient: Snapshot.shape.recipient,
+      refundAddress: Snapshot.shape.refundAddress,
+      sourceChain: Snapshot.shape.sourceChain,
+      sourceToken: Snapshot.shape.sourceToken,
+      status: Status,
+      subsidize: Snapshot.shape.subsidize,
+      updatedAt: z
+        .string()
+        .check(
+          z.describe('When the deposit address last materially changed (ISO 8601).'),
+          z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
+        ),
+    })
+    .check(z.describe('One reusable address for funding a Tempo account.'))
+
+  /** A reusable funding deposit address with terms sampled during creation. */
+  export const CreatedFundingDepositAddress = z
+    .object({
+      ...FundingDepositAddress.shape,
+      destinationAmount: Provider.schema.FundingQuote.shape.destinationAmount,
+      destinationAmountMin: Provider.schema.FundingQuote.shape.destinationAmountMin,
+      fees: z.array(Transfer.schema.Fee).check(z.describe('Fees applied to the quoted deposit.')),
+      quote: Provider.schema.QuoteDetails,
+      sourceAmount: Provider.schema.FundingQuote.shape.sourceAmount,
+    })
+    .check(z.describe('A reusable funding deposit address with current quoted delivery terms.'))
+}
+
+/** Stored public snapshot of a funding deposit address. */
+export type Snapshot = z.output<typeof schema.Snapshot>
+
+/** A funding deposit address as returned by reads. */
+export type Public = z.output<typeof schema.FundingDepositAddress>
+
+/** A funding deposit address returned by creation with current quoted terms. */
+export type Created = z.output<typeof schema.CreatedFundingDepositAddress>
+
+/** Creates a durable funding deposit address for an already-provisioned provider address. */
+export async function create(
+  db: Db.Db,
+  input: create.Input,
+): Promise<FundingDepositAddresses.Record> {
+  return FundingDepositAddresses.insert(db, record(input))
+}
+
+/** Creates or returns the reusable address for the same owner and route. */
+export async function createOrGet(
+  db: Db.Db,
+  input: createOrGet.Input,
+): Promise<createOrGet.ReturnType> {
+  const value = record(input)
+  const result = await FundingDepositAddresses.insertOrGet(db, {
+    match: {
+      destinationTokenKey: value.destinationTokenKey,
+      environment: value.environment,
+      orgId: value.orgId,
+      ...(value.projectId === null ? {} : { projectId: value.projectId }),
+      recipient: value.recipient,
+      refundAddress: value.refundAddress,
+      sourceChainId: value.sourceChainId,
+      sourceTokenKey: value.sourceTokenKey,
+      subsidize: value.subsidize,
+    },
+    record: value,
+  }).catch((cause) => {
+    if (cause instanceof FundingDepositAddresses.ConflictError) throw new ConflictError()
+    throw cause
+  })
+  if (result.providerId !== value.providerId) throw new ConflictError()
+  return { record: result, type: result.id === value.id ? 'created' : 'existing' }
+}
+
+export declare namespace createOrGet {
+  /** Fields required to persist or find a provisioned deposit address. */
+  type Input = create.Input
+
+  /** Whether provisioning created or matched the stored reusable address. */
+  type ReturnType = {
+    /** Stored reusable deposit address. */
+    record: FundingDepositAddresses.Record
+    /** Whether the provider address was newly stored or matched an existing identity. */
+    type: 'created' | 'existing'
+  }
+}
+
+function record(input: create.Input): FundingDepositAddresses.Record {
+  const now = input.now ?? new Date()
+  const parsed = schema.Snapshot.parse(input.snapshot)
+  const snapshot = {
+    ...parsed,
+    address: parsed.sourceChain.kind === 'evm' ? parsed.address.toLowerCase() : parsed.address,
+  }
+  return {
+    address: snapshot.address,
+    apiKeyId: input.apiKeyId,
+    createdAt: now.toISOString(),
+    deliveryStrategy: input.deliveryStrategy,
+    destinationTokenKey: snapshot.destinationToken.tokenKey,
+    environment: input.environment,
+    id: input.id ?? generateId(now),
+    lastPolledAt: null,
+    nextPollAt: now.toISOString(),
+    orgId: input.orgId,
+    pollFailureCount: 0,
+    pollLeaseUntil: null,
+    pollLeaseVersion: 0,
+    projectId: input.projectId ?? null,
+    providerOutputToken: input.providerOutputToken,
+    providerId: snapshot.provider.id,
+    providerRequestIds: input.providerRequestIds ?? [],
+    providerState: input.providerState ?? null,
+    recipient: snapshot.recipient,
+    refundAddress: snapshot.refundAddress,
+    snapshot,
+    sourceChainId: snapshot.sourceChain.id,
+    sourceTokenKey: snapshot.sourceToken.tokenKey,
+    status: 'active',
+    subsidize: snapshot.subsidize,
+    updatedAt: now.toISOString(),
+    version: 1,
+  }
+}
+
+export declare namespace create {
+  /** Fields required to persist a provisioned deposit address. */
+  type Input = {
+    /** API key that provisioned the address. */
+    apiKeyId: string
+    /** Responsibility for delivering the requested destination token. */
+    deliveryStrategy: DeliveryStrategy
+    /** Key environment the address belongs to. */
+    environment: 'production' | 'sandbox'
+    /** Address id override for deterministic tests. */
+    id?: string | undefined
+    /** Creation time override for deterministic tests. */
+    now?: Date | undefined
+    /** Owning organization id (`org_…`). */
+    orgId: string
+    /** Attributed project id for a project-scoped API key. */
+    projectId?: string | undefined
+    /** Token that the provider outputs on Tempo. */
+    providerOutputToken: Provider.TokenRef
+    /** Private provider request identifiers. */
+    providerRequestIds?: readonly string[] | undefined
+    /** Private bounded provider state. */
+    providerState?: ProviderState | undefined
+    /** Public address snapshot. */
+    snapshot: Snapshot
+  }
+}
+
+/** Applies a version-guarded funding deposit address status transition. */
+export async function transition(
+  db: Db.Db,
+  options: transition.Options,
+): Promise<transition.Result> {
+  const current = await FundingDepositAddresses.get(db, options.id)
+  if (!current) return { type: 'not_found' }
+  if (current.version !== options.expectedVersion) return { current, type: 'stale' }
+  if (!canTransition(current.status, options.status)) return { current, type: 'invalid' }
+
+  const updated = await FundingDepositAddresses.update(db, {
+    expectedVersion: options.expectedVersion,
+    id: options.id,
+    status: options.status,
+    updatedAt: new Date().toISOString(),
+    version: current.version + 1,
+  })
+  if (updated) return { record: updated, type: 'applied' }
+  const latest = await FundingDepositAddresses.get(db, options.id)
+  return latest ? { current: latest, type: 'stale' } : { type: 'not_found' }
+}
+
+export declare namespace transition {
+  /** Fields required for a guarded status transition. */
+  type Options = {
+    /** Version that the transition was computed against. */
+    expectedVersion: number
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** New lifecycle status. */
+    status: Status
+  }
+
+  /** Outcome of a guarded address transition. */
+  type Result =
+    | { record: FundingDepositAddresses.Record; type: 'applied' }
+    | { current: FundingDepositAddresses.Record; type: 'invalid' }
+    | { current: FundingDepositAddresses.Record; type: 'stale' }
+    | { type: 'not_found' }
+}
+
+/** Serializes a stored address to the public read shape. */
+export function toPublic(record: FundingDepositAddresses.Record): Public {
+  return schema.FundingDepositAddress.parse({
+    ...record.snapshot,
+    createdAt: record.createdAt,
+    id: record.id,
+    status: record.status,
+    subsidize: record.subsidize,
+    updatedAt: record.updatedAt,
+  })
+}
+
+/** Error thrown when a provider conflicts with a stored reusable address. */
+export class ConflictError extends Error {
+  override name = 'FundingDepositAddress.ConflictError'
+}

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

@@ -0,0 +1,297 @@
+import { AbiEvent, Base58, Hex } from 'ox'
+
+import * as FundingCatalog from '../../db/tables/fundingCatalog.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as TestRelay from '../../../test/Relay.js'
+import * as Chain from './Chain.js'
+import * as Evidence from './Evidence.js'
+
+const transferTopic = AbiEvent.getSelector('event Transfer(address,address,uint256)').slice(2)
+const db = TestApp.database()
+
+describe('resolveRpcUrls', () => {
+  test('prefers matching Worker overrides and retains catalog fallbacks', () => {
+    const ethereum = Chain.from({
+      id: 'eip155:1',
+      name: 'Ethereum',
+      rpcUrls: ['https://ethereum.catalog.test'],
+      slug: 'ethereum',
+    })
+    const solana = Chain.from({
+      id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      name: 'Solana',
+      rpcUrls: ['https://solana.catalog.test'],
+      slug: 'solana',
+    })
+    const tempo = Chain.from({
+      id: 'eip155:4217',
+      name: 'Tempo',
+      rpcUrls: ['https://tempo.catalog.test'],
+      slug: 'tempo',
+    })
+    const override = JSON.stringify({ 1: 'https://ethereum.worker.test' })
+
+    expect({
+      mappedEthereum: Evidence.resolveRpcUrls({
+        chain: ethereum,
+        defaultChainId: 4217,
+        rpcUrlEnv: override,
+      }),
+      mappedTempo: Evidence.resolveRpcUrls({
+        chain: tempo,
+        defaultChainId: 4217,
+        rpcUrlEnv: override,
+      }),
+      sharedEthereum: Evidence.resolveRpcUrls({
+        chain: ethereum,
+        defaultChainId: 4217,
+        rpcUrlEnv: 'https://tempo.worker.test',
+      }),
+      sharedSolana: Evidence.resolveRpcUrls({
+        chain: solana,
+        defaultChainId: 4217,
+        rpcUrlEnv: 'https://tempo.worker.test',
+      }),
+      sharedTempo: Evidence.resolveRpcUrls({
+        chain: tempo,
+        defaultChainId: 4217,
+        rpcUrlEnv: 'https://tempo.worker.test',
+      }),
+    }).toMatchInlineSnapshot(`
+      {
+        "mappedEthereum": [
+          "https://ethereum.worker.test",
+          "https://ethereum.catalog.test",
+        ],
+        "mappedTempo": [
+          "https://tempo.catalog.test",
+        ],
+        "sharedEthereum": [
+          "https://ethereum.catalog.test",
+        ],
+        "sharedSolana": [
+          "https://solana.catalog.test",
+        ],
+        "sharedTempo": [
+          "https://tempo.worker.test",
+          "https://tempo.catalog.test",
+        ],
+      }
+    `)
+  })
+})
+
+describe('createVerifier', () => {
+  test('verifies finalized Solana and one-confirmation Tron token transfers', async () => {
+    const tron = TestFunding.depositAddressSnapshot()
+    const solana = TestFunding.transferSnapshot({
+      sourceChain: {
+        addressFormat: 'base58',
+        id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        kind: 'solana',
+        name: 'Solana',
+      },
+      sourceToken: {
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        currency: 'USD',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+        tokenKey:
+          'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        verified: true,
+      },
+    })
+    const solanaRecipient = 'RelayRecipient11111111111111111111111111111'
+    const refreshedSolana = {
+      ...solana.sourceChain,
+      id: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
+      name: 'Solana Devnet',
+    } as const
+    const server = await TestRelay.createServer((request, response) => {
+      request.resume()
+      if (request.url === '/unavailable') {
+        response.writeHead(503)
+        response.end()
+        return
+      }
+      const result = request.url?.includes('getnowblock')
+        ? { block_header: { raw_data: { number: 150 } } }
+        : request.url?.includes('gettransactioninfobyid')
+          ? {
+              blockNumber: 150,
+              id: 'tron-transaction',
+              log: [
+                {
+                  address: tronHex(tron.sourceToken.address).slice(-40),
+                  data: 1_000_000n.toString(16).padStart(64, '0'),
+                  topics: [
+                    transferTopic,
+                    `0x${'66'.repeat(20).padStart(64, '0')}`,
+                    `0x${tronHex(tron.address).slice(-40).padStart(64, '0')}`,
+                  ],
+                },
+              ],
+              receipt: { result: 'SUCCESS' },
+            }
+          : {
+              meta: {
+                err: null,
+                postTokenBalances: [
+                  {
+                    accountIndex: 1,
+                    mint: solana.sourceToken.address,
+                    owner: solanaRecipient,
+                  },
+                ],
+              },
+              transaction: {
+                message: {
+                  accountKeys: [
+                    'Sender1111111111111111111111111111111111',
+                    'RecipientTokenAccount',
+                  ],
+                  instructions: [
+                    {
+                      parsed: {
+                        info: {
+                          authority: 'Sender1111111111111111111111111111111111',
+                          destination: 'RecipientTokenAccount',
+                          mint: solana.sourceToken.address,
+                          tokenAmount: { amount: '2000000' },
+                        },
+                        type: 'transferChecked',
+                      },
+                      program: 'spl-token',
+                    },
+                  ],
+                },
+              },
+            }
+      response.writeHead(200, { 'content-type': 'application/json' })
+      response.end(
+        request.url === '/'
+          ? JSON.stringify({ id: 1, jsonrpc: '2.0', result })
+          : JSON.stringify(result),
+      )
+    })
+
+    try {
+      vi.useFakeTimers({ now: new Date('2027-01-01T00:00:00.000Z') })
+      await FundingCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: solana.sourceChain.id as Chain.Id,
+            name: solana.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [new URL('/unavailable', server.url).toString(), server.url],
+            slug: 'solana',
+          },
+          {
+            aliases: [],
+            id: tron.sourceChain.id as Chain.Id,
+            name: tron.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [new URL('/unavailable', server.url).toString(), server.url],
+            slug: 'tron',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const verify = Evidence.createVerifier({
+        db,
+      })
+      const solanaEvidence = await verify({
+        chain: solana.sourceChain,
+        recipient: solanaRecipient,
+        token: solana.sourceToken,
+        transactionHash: 'solana-transaction',
+      })
+      const tronEvidence = await verify({
+        chain: tron.sourceChain,
+        recipient: tron.address,
+        token: tron.sourceToken,
+        transactionHash: 'tron-transaction',
+      })
+      await FundingCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: refreshedSolana.id as Chain.Id,
+            name: refreshedSolana.name,
+            parentChainId: null,
+            rpcUrls: [server.url],
+            slug: 'solana-devnet',
+          },
+          {
+            aliases: [],
+            id: solana.sourceChain.id as Chain.Id,
+            name: solana.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [new URL('/unavailable', server.url).toString(), server.url],
+            slug: 'solana',
+          },
+          {
+            aliases: [],
+            id: tron.sourceChain.id as Chain.Id,
+            name: tron.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [new URL('/unavailable', server.url).toString(), server.url],
+            slug: 'tron',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      await vi.advanceTimersByTimeAsync(60_001)
+      const refreshedSolanaEvidence = await verify({
+        chain: refreshedSolana,
+        recipient: solanaRecipient,
+        token: solana.sourceToken,
+        transactionHash: 'solana-refreshed-transaction',
+      })
+
+      expect({ refreshedSolanaEvidence, solanaEvidence, tronEvidence }).toMatchInlineSnapshot(`
+        {
+          "refreshedSolanaEvidence": [
+            {
+              "amount": "2000000",
+              "sender": "Sender1111111111111111111111111111111111",
+              "transactionHash": "solana-refreshed-transaction",
+              "transferIndex": 0,
+            },
+          ],
+          "solanaEvidence": [
+            {
+              "amount": "2000000",
+              "sender": "Sender1111111111111111111111111111111111",
+              "transactionHash": "solana-transaction",
+              "transferIndex": 0,
+            },
+          ],
+          "tronEvidence": [
+            {
+              "amount": "1000000",
+              "sender": "TKJebW6SdoJhgkKU13BeKCbrMzT6HeQhJ6",
+              "transactionHash": "tron-transaction",
+              "transferIndex": 0,
+            },
+          ],
+        }
+      `)
+    } finally {
+      vi.useRealTimers()
+      await server.closeAsync()
+    }
+  })
+})
+
+function tronHex(address: string) {
+  return Hex.fromBytes(Base58.toBytes(address).slice(0, 21)).slice(2)
+}