tapimo 0.7.1 → 0.8.0

package/src/internal/funding/Subsidy.local.test.ts

@@ -0,0 +1,152 @@
+/** @module-tag localnet */
+
+import { waitForTransactionReceipt } from 'viem/actions'
+import { Actions, Addresses } from 'viem/tempo'
+import { TxEnvelopeTempo } from 'ox/tempo'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as TestTempo from '../../../test/Tempo.js'
+import * as Subsidy from './Subsidy.js'
+
+const account = TestTempo.accounts[6]!
+const recipient = TestTempo.accounts[7]!
+const runtime = Runtime.get()
+const client = TestTempo.getClient()
+const settler = Subsidy.create({
+  account,
+  getClient: TestTempo.readClient(),
+  policy: { maxAmount: '10' },
+})
+
+beforeAll(async () => {
+  await Actions.faucet.fundSync(client, { account, timeout: 60_000 })
+})
+
+describe.skipIf(runtime.mode !== 'localnet')('create', () => {
+  test('transfers a pathUSD subsidy through a persisted signed transaction', async () => {
+    const before = await Actions.token.getBalance(client, {
+      account: recipient.address,
+      decimals: 6,
+      token: Addresses.pathUsd,
+    })
+    const prepared = await settler.prepare({
+      amount: 100_000n,
+      depositId: 'fdp_local_pathusd',
+      recipient: recipient.address,
+      token: Addresses.pathUsd,
+    })
+    const envelope = TxEnvelopeTempo.deserialize(prepared.transaction as TxEnvelopeTempo.Serialized)
+
+    expect({
+      nonceKey: envelope.nonceKey,
+      validBefore: envelope.validBefore,
+    }).toMatchInlineSnapshot(`
+      {
+        "nonceKey": 30469680684220070457389426308647765119962481996559904707083080710737939923517n,
+        "validBefore": undefined,
+      }
+    `)
+
+    await settler.broadcast(prepared)
+    await waitForTransactionReceipt(client, { hash: prepared.hash })
+    await expect
+      .poll(async () => (await settler.status({ hash: prepared.hash })).type)
+      .toBe('success')
+    const [after, status] = await Promise.all([
+      Actions.token.getBalance(client, {
+        account: recipient.address,
+        decimals: 6,
+        token: Addresses.pathUsd,
+      }),
+      settler.status({ hash: prepared.hash }),
+    ])
+
+    expect({ delivered: after.amount - before.amount, status }).toMatchInlineSnapshot(
+      {
+        status: { tempoGasPaid: expect.any(String) },
+      },
+      `
+      {
+        "delivered": 100000n,
+        "status": {
+          "tempoGasPaid": Any<String>,
+          "type": "success",
+        },
+      }
+    `,
+    )
+  })
+
+  test('buys the exact destination amount with pathUSD and transfers it atomically', async () => {
+    const destinationToken = runtime.fixtures?.crossTokenTransfer?.destinationToken
+    if (!destinationToken) throw new Error('Expected a seeded local DEX pair.')
+    const before = await Actions.token.getBalance(client, {
+      account: recipient.address,
+      decimals: 6,
+      token: destinationToken,
+    })
+    const prepared = await settler.prepare({
+      amount: 100_000n,
+      depositId: 'fdp_local_activity_usd',
+      recipient: recipient.address,
+      token: destinationToken,
+    })
+
+    await settler.broadcast(prepared)
+    await waitForTransactionReceipt(client, { hash: prepared.hash })
+    await expect
+      .poll(async () => (await settler.status({ hash: prepared.hash })).type)
+      .toBe('success')
+    const [after, status] = await Promise.all([
+      Actions.token.getBalance(client, {
+        account: recipient.address,
+        decimals: 6,
+        token: destinationToken,
+      }),
+      settler.status({ hash: prepared.hash }),
+    ])
+
+    expect({ delivered: after.amount - before.amount, status }).toMatchInlineSnapshot(
+      {
+        status: { tempoGasPaid: expect.any(String) },
+      },
+      `
+      {
+        "delivered": 100000n,
+        "status": {
+          "tempoGasPaid": Any<String>,
+          "type": "success",
+        },
+      }
+    `,
+    )
+  })
+
+  test('reports unavailable native DEX liquidity', async () => {
+    const { token } = await Actions.token.createSync(TestTempo.getClient({ account }), {
+      currency: 'USD',
+      name: 'Unlisted USD',
+      symbol: 'UNLISTED',
+    })
+
+    await expect(
+      settler.prepare({
+        amount: 100_000n,
+        depositId: 'fdp_local_unlisted',
+        recipient: recipient.address,
+        token,
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Funding.Subsidy.LiquidityUnavailableError]`)
+  })
+
+  test('reports unavailable pathUSD balance from transaction simulation', async () => {
+    await expect(
+      settler.prepare({
+        amount: 2n ** 120n,
+        depositId: 'fdp_local_insufficient_balance',
+        recipient: recipient.address,
+        token: Addresses.pathUsd,
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Funding.Subsidy.BalanceUnavailableError]`)
+  })
+})

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

@@ -0,0 +1,75 @@
+import { privateKeyToAccount } from 'viem/accounts'
+
+import * as TestFunding from '../../../test/Funding.js'
+import * as Viem from '../Viem.js'
+import * as Subsidy from './Subsidy.js'
+
+const privateKey = `0x${'11'.repeat(32)}` as const
+
+describe('supports', () => {
+  test('accepts only corresponding USD routes within the deposit limit', () => {
+    const route = TestFunding.transferSnapshot()
+    expect({
+      aboveLimit: Subsidy.supports(
+        { maxAmount: '1' },
+        {
+          amount: '1000001',
+          destinationToken: route.destinationToken,
+          sourceToken: route.sourceToken,
+        },
+      ),
+      invalidLimit: Subsidy.supports(
+        { maxAmount: 'invalid' },
+        {
+          amount: '1000000',
+          destinationToken: route.destinationToken,
+          sourceToken: route.sourceToken,
+        },
+      ),
+      withinLimit: Subsidy.supports(
+        { maxAmount: '1' },
+        {
+          amount: '1000000',
+          destinationToken: route.destinationToken,
+          sourceToken: route.sourceToken,
+        },
+      ),
+      wrongCurrency: Subsidy.supports(
+        { maxAmount: '1' },
+        {
+          amount: '1000000',
+          destinationToken: { ...route.destinationToken, currency: 'EUR' },
+          sourceToken: route.sourceToken,
+        },
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "aboveLimit": false,
+        "invalidLimit": false,
+        "withinLimit": true,
+        "wrongCurrency": false,
+      }
+    `)
+  })
+})
+
+describe('create', () => {
+  test('exposes the dedicated account and policy without network access', () => {
+    const account = privateKeyToAccount(privateKey)
+    const policy = { maxAmount: '10' }
+    const settler = Subsidy.create({
+      account,
+      getClient: Viem.createGetClient(),
+      policy,
+    })
+
+    expect({ account: settler.account, policy: settler.policy }).toMatchInlineSnapshot(`
+      {
+        "account": "0x19E7E376E7C213B7E7e7e46cc70A5dD086DAff2A",
+        "policy": {
+          "maxAmount": "10",
+        },
+      }
+    `)
+  })
+})

package/src/internal/funding/Subsidy.ts

@@ -0,0 +1,260 @@
+import { Address as core_Address, Hash, Hex, Value } from 'ox'
+import {
+  type Address,
+  BaseError,
+  ContractFunctionRevertedError,
+  type LocalAccount,
+  TransactionReceiptNotFoundError,
+} from 'viem'
+import {
+  getTransactionReceipt,
+  prepareTransactionRequest,
+  sendRawTransaction,
+  signTransaction,
+} from 'viem/actions'
+import { Actions, Addresses } from 'viem/tempo'
+
+import * as Fees from '../Fees.js'
+import type * as Viem from '../Viem.js'
+import type * as Provider from './Provider.js'
+
+const slippageBps = 100n
+const slippageDenominator = 10_000n
+
+/** Maximum subsidized deposit value expressed as a decimal USD amount. */
+export type Policy = {
+  /** Maximum source deposit value that Tempo will subsidize. */
+  maxAmount: string
+}
+
+/** Returns whether one USD stablecoin deposit is within the subsidy policy. */
+export function supports(policy: Policy, options: supports.Options): boolean {
+  if (
+    options.destinationToken.currency !== 'USD' ||
+    options.sourceToken.currency !== options.destinationToken.currency
+  )
+    return false
+  const maximum = (() => {
+    try {
+      return Value.from(policy.maxAmount, options.sourceToken.decimals)
+    } catch {
+      return 0n
+    }
+  })()
+  return maximum > 0n && BigInt(options.amount) <= maximum
+}
+
+export declare namespace supports {
+  /** Route and source amount evaluated against a subsidy policy. */
+  type Options = {
+    /** Source amount in base units. */
+    amount: string
+    /** Token that the recipient receives on Tempo. */
+    destinationToken: Provider.TokenRef
+    /** Token deposited on the source chain. */
+    sourceToken: Provider.TokenRef
+  }
+}
+
+/** Prepares and submits durable pathUSD-funded subsidy transactions. */
+export type Settler = {
+  /** Tempo account that supplies pathUSD. */
+  account: Address
+  /** Broadcasts one previously persisted signed transaction. */
+  broadcast(parameters: Settler.broadcast.Parameters): Promise<void>
+  /** Maximum subsidized deposit policy enforced at creation and settlement. */
+  policy: Policy
+  /** Prepares one signed transaction without broadcasting it. */
+  prepare(parameters: Settler.prepare.Parameters): Promise<Settler.prepare.ReturnType>
+  /** Reads the receipt state of one persisted subsidy transaction. */
+  status(parameters: Settler.status.Parameters): Promise<Settler.status.ReturnType>
+}
+
+/** Contracts for subsidy settlement operations. */
+export declare namespace Settler {
+  /** Contracts for broadcasting one signed subsidy transaction. */
+  namespace broadcast {
+    /** Persisted transaction passed to the broadcaster. */
+    type Parameters = {
+      /** Expected transaction hash. */
+      hash: Hex.Hex
+      /** Signed Tempo transaction bytes. */
+      transaction: Hex.Hex
+    }
+  }
+
+  /** Contracts for preparing one subsidy transaction. */
+  namespace prepare {
+    /** Deposit deficit used to construct a subsidy transaction. */
+    type Parameters = {
+      /** Destination-token deficit in base units. */
+      amount: bigint
+      /** Deposit id hashed into the destination transfer memo. */
+      depositId: string
+      /** Tempo account that receives the subsidy. */
+      recipient: Address
+      /** Destination token address supplied by Tempo. */
+      token: Address
+    }
+
+    /** Signed transaction prepared for durable persistence. */
+    type ReturnType = {
+      /** Hash of the signed transaction. */
+      hash: Hex.Hex
+      /** Signed Tempo transaction bytes. */
+      transaction: Hex.Hex
+    }
+  }
+
+  /** Contracts for reading subsidy transaction state. */
+  namespace status {
+    /** Persisted transaction inspected by receipt hash. */
+    type Parameters = {
+      /** Persisted transaction hash. */
+      hash: Hex.Hex
+    }
+
+    /** Receipt state used by reconciliation. */
+    type ReturnType =
+      | {
+          /** No verified receipt exists yet. */
+          type: 'pending'
+        }
+      | {
+          /** Tempo gas cost persisted for subsidy accounting, in fee-token base units. */
+          tempoGasPaid: string
+          /** Verified settlement execution result. */
+          type: 'reverted' | 'success'
+        }
+  }
+}
+
+/** Creates a subsidy settler backed by a Tempo account that holds pathUSD. */
+export function create(options: create.Options): Settler {
+  const client = options.getClient()
+  return {
+    account: options.account.address,
+    async broadcast(parameters) {
+      const hash = await sendRawTransaction(client, {
+        serializedTransaction: parameters.transaction,
+      })
+      if (!Hex.isEqual(hash, parameters.hash)) throw new TransactionHashMismatchError()
+    },
+    policy: options.policy,
+    async prepare(parameters) {
+      const destinationToken = parameters.token
+      const direct = core_Address.isEqual(destinationToken, Addresses.pathUsd)
+      const memo = Hash.keccak256(Hex.fromString(parameters.depositId))
+      const nonceKey = (BigInt(memo) >> 1n) + 1n
+      const maximumAmount = await (async () => {
+        if (direct) return parameters.amount
+        const quotedAmount = await Actions.dex
+          .getBuyQuote(client, {
+            amountOut: parameters.amount,
+            tokenIn: Addresses.pathUsd,
+            tokenOut: destinationToken,
+          })
+          .catch((cause) => {
+            if (hasRevert(cause, ['InsufficientLiquidity', 'PairDoesNotExist']))
+              throw new LiquidityUnavailableError()
+            throw cause
+          })
+        if (quotedAmount === 0n) throw new LiquidityUnavailableError()
+        return (
+          (quotedAmount * (slippageDenominator + slippageBps) + slippageDenominator - 1n) /
+          slippageDenominator
+        )
+      })()
+      const calls = direct
+        ? [
+            Actions.token.transfer.call(client, {
+              amount: parameters.amount,
+              memo,
+              to: parameters.recipient,
+              token: destinationToken,
+            }),
+          ]
+        : [
+            Actions.token.approve.call(client, {
+              amount: maximumAmount,
+              spender: Addresses.stablecoinDex,
+              token: Addresses.pathUsd,
+            }),
+            Actions.dex.buy.call({
+              amountOut: parameters.amount,
+              maxAmountIn: maximumAmount,
+              tokenIn: Addresses.pathUsd,
+              tokenOut: destinationToken,
+            }),
+            Actions.token.transfer.call(client, {
+              amount: parameters.amount,
+              memo,
+              to: parameters.recipient,
+              token: destinationToken,
+            }),
+          ]
+      const request = await prepareTransactionRequest(client, {
+        account: options.account,
+        calls,
+        // A stable per-deposit nonce lets durable retries rebroadcast without paying twice.
+        nonceKey,
+      }).catch((cause) => {
+        if (hasRevert(cause, ['InsufficientBalance'])) throw new BalanceUnavailableError()
+        throw cause
+      })
+      const transaction = await signTransaction(client, {
+        ...request,
+        account: options.account,
+      })
+      return { hash: Hash.keccak256(transaction), transaction }
+    },
+    async status(parameters) {
+      const receipt = await getTransactionReceipt(client, parameters).catch((cause) => {
+        if (cause instanceof TransactionReceiptNotFoundError) return undefined
+        throw cause
+      })
+      if (!receipt) return { type: 'pending' }
+      return {
+        tempoGasPaid: Fees.fromGas(receipt.gasUsed, receipt.effectiveGasPrice).toString(),
+        type: receipt.status === 'success' ? 'success' : 'reverted',
+      }
+    },
+  }
+}
+
+export declare namespace create {
+  /** Dependencies and policy for one subsidy settler. */
+  type Options = {
+    /** Tempo account that signs subsidies and holds pathUSD. */
+    account: LocalAccount
+    /** Trusted Tempo RPC client resolver. */
+    getClient: Viem.GetClient
+    /** Maximum subsidized deposit policy. */
+    policy: Policy
+  }
+}
+
+function hasRevert(cause: unknown, names: readonly string[]): boolean {
+  if (!(cause instanceof BaseError)) return false
+  const decoded = cause.walk(
+    (error) =>
+      error instanceof ContractFunctionRevertedError &&
+      Boolean(error.data?.errorName && names.includes(error.data.errorName)),
+  )
+  return Boolean(decoded) || names.some((name) => cause.details.includes(`${name}(`))
+}
+
+/** The subsidy account lacks enough pathUSD. */
+export class BalanceUnavailableError extends Error {
+  override name = 'Funding.Subsidy.BalanceUnavailableError'
+}
+
+/** The Tempo DEX cannot quote the required destination amount. */
+export class LiquidityUnavailableError extends Error {
+  override name = 'Funding.Subsidy.LiquidityUnavailableError'
+}
+
+/** The RPC returned a hash that differs from the persisted transaction. */
+export class TransactionHashMismatchError extends Error {
+  override name = 'Funding.Subsidy.TransactionHashMismatchError'
+}

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

@@ -0,0 +1,47 @@
+import * as Chain from './Chain.js'
+import * as Token from './Token.js'
+
+const base = Chain.from({ id: 'eip155:8453', name: 'Base', slug: 'base' })
+
+describe('from', () => {
+  test('creates a token with chain-specific metadata', () => {
+    const token = Token.from({
+      chains: {
+        [base.id]: {
+          address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+          decimals: 6,
+          standard: 'ERC-20',
+        },
+      },
+      currency: 'USD',
+      name: 'USD Coin',
+      slug: 'usdc',
+      symbol: 'USDC',
+    })
+
+    const resolved = base({ tokens: [token] }).tokens[0]
+    expect(resolved).toMatchObject({
+      address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+      decimals: 6,
+      standard: 'ERC-20',
+      symbol: 'USDC',
+    })
+    expect(resolved?.chain.id).toBe('eip155:8453')
+  })
+})
+
+describe('resolve', () => {
+  test('rejects a token that is unavailable on the chain', () => {
+    const token = Token.from({
+      chains: {},
+      currency: 'USD',
+      name: 'USD Coin',
+      slug: 'usdc',
+      symbol: 'USDC',
+    })
+
+    expect(() => base({ tokens: [token] })).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Token.MissingChainError]`,
+    )
+  })
+})

package/src/internal/funding/Token.ts

@@ -0,0 +1,59 @@
+import type * as Chain from './Chain.js'
+
+/** A token accepted or returned by a funding provider. */
+export type Token = {
+  /** Chain-specific token metadata keyed by CAIP-2 chain id. */
+  chains: Partial<Record<Chain.Id, ChainConfig>>
+  /** Monetary denomination represented by the token. */
+  currency: string
+  /** Human-readable token name. */
+  name: string
+  /** Stable token segment used in quote identifiers. */
+  slug: string
+  /** Short token ticker symbol. */
+  symbol: string
+}
+
+/** Chain-specific token metadata. */
+export type ChainConfig = {
+  /** Contract address, mint, or issuer address on the chain. */
+  address: string
+  /** Number of decimal places used by the token on the chain. */
+  decimals: number
+  /** Chain-specific token name override. */
+  name?: string | undefined
+  /** Token standard on the chain. */
+  standard: string
+}
+
+/** A token resolved to one funding chain. */
+export type Resolved = Omit<Token, 'chains'> &
+  Omit<ChainConfig, 'name'> & {
+    /** Chain where the token exists. */
+    chain: Chain.Chain
+    /** Human-readable token name for this chain. */
+    name: string
+  }
+
+/** Creates a canonical funding token. */
+export function from<const token extends Token>(options: token): token {
+  return options
+}
+
+/** Resolves a funding token to its metadata on one chain. */
+export function resolve(token: Token, chain: Chain.Chain): Resolved {
+  const config = token.chains[chain.id]
+  if (!config) throw new MissingChainError()
+  const { chains: _chains, ...metadata } = token
+  return {
+    ...metadata,
+    ...config,
+    chain,
+    name: config.name ?? token.name,
+  }
+}
+
+/** Error thrown when a token is not configured for a selected chain. */
+export class MissingChainError extends Error {
+  override name = 'Funding.Token.MissingChainError'
+}