tapimo 0.15.1 → 0.18.0

package/src/internal/routes/TransferSubsidy.ts

@@ -25,14 +25,43 @@ import {
   readContract,
   sendRawTransaction,
 } from 'viem/actions'
+import { Actions } from 'viem/tempo'
 
+import * as Fees from '../Fees.js'
 import * as Viem from '../Viem.js'
-import type * as Chain from './Chain.js'
+import * as Chain from './Chain.js'
 import type * as Provider from './Provider.js'
 
+/** Returns whether a wallet transfer can receive a destination subsidy. */
+export function supportsRoute(options: supportsRoute.Options): boolean {
+  const tempo = `eip155:${options.tempoChainId}`
+  return (
+    (options.destinationChainId === tempo && options.sourceChainId !== tempo) ||
+    (options.sourceChainId === tempo &&
+      [
+        'eip155:1',
+        'eip155:8453',
+        'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        'tron:0x2b6653dc',
+      ].includes(options.destinationChainId))
+  )
+}
+
+export declare namespace supportsRoute {
+  /** Chain identifiers used to check subsidy eligibility. */
+  type Options = {
+    /** Destination CAIP-2 chain identifier. */
+    destinationChainId: string
+    /** Source CAIP-2 chain identifier. */
+    sourceChainId: string
+    /** Tempo chain configured for the application. */
+    tempoChainId: number
+  }
+}
+
 /** Read-only destination subsidy inventory available during action creation. */
 export type Inventory = {
-  /** Account that supplies destination USDC and native gas. */
+  /** Account that supplies destination tokens and transaction fees. */
   account: Address
   /** Verifies token and gas capacity without accessing signing material. */
   check(parameters: Inventory.check.Parameters): Promise<Inventory.check.Result>
@@ -75,7 +104,7 @@ export type Transaction = {
   hash: Hex.Hex
   /** EOA nonce reserved for this transaction. */
   nonce: number
-  /** Worst-case native gas amount reserved for this transaction. */
+  /** Worst-case gas cost in wei, or rounded attodollars on Tempo. */
   nativeAmount?: string | undefined
   /** Signed EVM transaction bytes. */
   transaction: Hex.Hex
@@ -109,7 +138,7 @@ export function read(value: unknown): Transaction | undefined {
 
 /** Prepares and submits ERC-20 destination subsidy transactions. */
 export type Settler = {
-  /** Account that supplies destination USDC and native gas. */
+  /** Account that supplies destination tokens and transaction fees. */
   account: Address
   /** Broadcasts one previously persisted signed transaction. */
   broadcast(parameters: { chain: Chain.Chain; transaction: Transaction }): Promise<void>
@@ -145,10 +174,12 @@ export declare namespace Settler {
 
     /** Inventory reserved while serializing transactions for one signer. */
     type Reservations = {
-      /** Native gas amount promised by unsettled transactions. */
+      /** Gas cost promised by unsettled transactions, in wei or rounded attodollars on Tempo. */
       nativeAmount: bigint
       /** Token amount promised by unsettled transactions. */
       tokenAmount: bigint
+      /** Delivery commitments by lowercase token address, including tokens used for Tempo fees. */
+      tokenAmounts: Record<string, bigint>
     }
   }
 
@@ -220,7 +251,7 @@ export function createInventory(options: createInventory.Options): Inventory {
 export declare namespace createInventory {
   /** Dependencies for one destination subsidy inventory checker. */
   type Options = {
-    /** EVM account funded with destination USDC and native gas. */
+    /** EVM account funded with destination tokens and transaction fees. */
     account: Address
     /** Fetch implementation used for destination RPC requests. */
     fetch: typeof globalThis.fetch
@@ -283,11 +314,14 @@ export function create(options: create.Options): Settler {
         throw cause
       })
       if (!receipt) return { broadcast: true, type: 'pending' }
-      const [canonical, finalized] = await Promise.all([
+      const [canonical, head] = await Promise.all([
         getBlock(client, { blockNumber: receipt.blockNumber, includeTransactions: false }),
-        getBlock(client, { blockTag: 'finalized', includeTransactions: false }),
+        getBlock(client, {
+          blockTag: Chain.settlementBlockTag(parameters.chain),
+          includeTransactions: false,
+        }),
       ])
-      if (canonical.hash !== receipt.blockHash || receipt.blockNumber > finalized.number)
+      if (canonical.hash !== receipt.blockHash || receipt.blockNumber > head.number)
         return { broadcast: false, type: 'pending' }
       if (receipt.status !== 'success') return { type: 'reverted' }
       const matched = receipt.logs.some((log) => {
@@ -344,11 +378,52 @@ async function checkInventory(
     }),
     ...(parameters.nonce === undefined ? {} : { nonce: parameters.nonce }),
     to: parameters.token,
+    // Horcrux signs EIP-1559 envelopes; inventory and signing must estimate the same fee fields.
+    type: 'eip1559',
     value: 0n,
   } as never)
-  const gasPrice = request.maxFeePerGas ?? request.gasPrice
+  // eth_fillTransaction can include an effective gasPrice, which is not a signed EIP-1559 fee field.
+  delete request.gasPrice
+  const gasPrice = request.maxFeePerGas
   if (request.gas === undefined || gasPrice === undefined) throw new BalanceUnavailableError()
   const nativeAmount = request.gas * gasPrice
+  if (parameters.chain.slug === 'tempo') {
+    const preferred = await Actions.fee.getUserToken(client, { account: address })
+    const feeToken = preferred?.address ?? parameters.token
+    const deliveryToken = parameters.token.toLowerCase()
+    const feeTokenAddress = feeToken.toLowerCase()
+    const sameToken = feeTokenAddress === deliveryToken
+    const feeBalance = sameToken
+      ? tokenBalance
+      : await readContract(client, {
+          abi: erc20Abi,
+          address: feeToken,
+          args: [address],
+          functionName: 'balanceOf',
+        })
+    const feeAmount = Fees.fromGas(request.gas, gasPrice)
+    // Reserve each fee cap after rounding to TIP-20 units. Native balance is a constant on Tempo.
+    const reservedFees = Fees.fromGas(1n, parameters.reservations.nativeAmount)
+    const reservedTokens = parameters.reservations.tokenAmounts[feeTokenAddress] ?? 0n
+    // Fee preferences can change before settlement, so each delivery token must cover pending gas.
+    if (
+      tokenBalance <
+        parameters.amount + parameters.reservations.tokenAmount + reservedFees + feeAmount ||
+      feeBalance < reservedTokens + reservedFees + feeAmount + (sameToken ? parameters.amount : 0n)
+    )
+      throw new BalanceUnavailableError()
+    for (const [token, amount] of Object.entries(parameters.reservations.tokenAmounts)) {
+      if (token === deliveryToken || token === feeTokenAddress) continue
+      const balance = await readContract(client, {
+        abi: erc20Abi,
+        address: token as Address,
+        args: [address],
+        functionName: 'balanceOf',
+      })
+      if (balance < amount + reservedFees + feeAmount) throw new BalanceUnavailableError()
+    }
+    return { nativeAmount: feeAmount * Fees.scalingFactor, request }
+  }
   if ((await getBalance(client, { address })) < nativeAmount + parameters.reservations.nativeAmount)
     throw new BalanceUnavailableError()
   return { nativeAmount, request }
@@ -357,7 +432,7 @@ async function checkInventory(
 export declare namespace create {
   /** Dependencies for one destination subsidy settler. */
   type Options = {
-    /** EVM account funded with destination USDC and native gas. */
+    /** EVM account funded with destination tokens and transaction fees. */
     account: LocalAccount
     /** Fetch implementation used for destination RPC requests. */
     fetch: typeof globalThis.fetch
@@ -412,7 +487,7 @@ function isNonceTooLowBroadcastError(cause: unknown): boolean {
   return /nonce too low/i.test(message)
 }
 
-/** The subsidy account lacks destination token inventory or native gas. */
+/** The subsidy account lacks destination token inventory or transaction fee funds. */
 export class BalanceUnavailableError extends Error {
   override name = 'Routes.TransferSubsidy.BalanceUnavailableError'
 }

package/src/internal/routes/TronTransferSettlement.ts

@@ -0,0 +1,212 @@
+import * as Value from '../Value.js'
+import * as Transfer from './Transfer.js'
+import type * as TransferSettlement from './TransferSettlement.js'
+import * as TronTransferSubsidy from './TronTransferSubsidy.js'
+
+const tronFinalityGraceMs = 180_000
+
+/** Advances a persisted Tron subsidy through signing, broadcast, and finality. */
+export async function settle(options: settle.Options): Promise<TransferSettlement.Result> {
+  let current = options.current
+  const existing = TronTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+  const prepared = TronTransferSubsidy.readPrepared(
+    current.providerState?.['tronTransferSubsidyPrepared'],
+  )
+  const terms = {
+    account: existing?.account ?? prepared?.account ?? current.subsidyAccount ?? '',
+    amount: options.deficit,
+    chainId: options.destinationChain.id,
+    recipient: current.snapshot.recipient,
+    token: current.snapshot.destinationToken.address,
+  }
+  if (
+    (existing && !TronTransferSubsidy.matchesTerms(existing, terms)) ||
+    (prepared && !TronTransferSubsidy.matchesTerms(prepared, terms))
+  ) {
+    options.recordSubsidy('evidence_conflict')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'Destination subsidy evidence conflicts with the verified delivery.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  const account = existing?.account ?? prepared?.account ?? current.subsidyAccount
+  const settler = existing
+    ? options.settlers?.[0]
+    : options.settlers?.find((entry) => entry.account === account)
+  if (!settler) {
+    options.recordSubsidy('unavailable')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'Destination subsidy settlement is unavailable.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  const commitment = current.subsidyCommitmentAmount
+  if (!existing && !prepared && (!commitment || options.deficit > BigInt(commitment.baseUnits))) {
+    options.recordSubsidy('routes_subsidy_limit_exceeded')
+    return {
+      reason: {
+        code: 'routes_subsidy_limit_exceeded',
+        message: 'The required destination subsidy exceeds its approved commitment.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  const recipient = current.snapshot.recipient
+  const token = current.snapshot.destinationToken.address
+  const subsidyAmount = Value.tokenAmount({
+    baseUnits: options.deficit,
+    currency: current.snapshot.destinationToken.currency,
+    decimals: current.snapshot.destinationToken.decimals,
+  })
+  let signed = existing
+  if (!signed) {
+    const result = await Transfer.prepareTronSubsidy(options.db, {
+      account: settler.account,
+      chainId: options.destinationChain.id,
+      id: current.id,
+      orgId: current.orgId,
+      prepare: ({ reservations }) =>
+        settler.prepare({
+          amount: options.deficit,
+          chain: options.destinationChain,
+          recipient,
+          reservations,
+          token,
+        }),
+      subsidyAmount,
+      tokenAddress: token,
+    }).catch((cause) => {
+      if (cause instanceof TronTransferSubsidy.BalanceUnavailableError) return 'balance' as const
+      if (cause instanceof Transfer.SubsidySignerBlockedError) return 'blocked' as const
+      throw cause
+    })
+    if (result === 'balance' || result === 'blocked') {
+      options.recordSubsidy(result === 'balance' ? 'balance_unavailable' : 'signer_blocked')
+      return {
+        reason: {
+          code: result === 'balance' ? 'subsidy_balance_unavailable' : 'subsidy_failed',
+          message:
+            result === 'balance'
+              ? 'Tempo lacks enough destination token inventory or native gas.'
+              : 'Destination subsidy settlement requires operator recovery.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    if (result.type === 'not_found' || result.type === 'invalid') return { type: 'pending' }
+    current = result.record
+    if ('references' in result && result.references && options.dispatchTransferUpdates)
+      await options.dispatchTransferUpdates(result.references)
+    if (result.type === 'signed' || result.type === 'shared') {
+      signed = result.signed
+      if (result.type === 'shared') options.recordSubsidy('shared')
+    } else {
+      options.recordSubsidy('prepared')
+      if (result.prepared.expiresAt <= Date.now()) {
+        options.recordSubsidy('expired')
+        return {
+          reason: {
+            code: 'subsidy_failed',
+            message: 'The prepared Tron subsidy expired before signing.',
+          },
+          record: current,
+          type: 'action-required',
+        }
+      }
+      // The persisted transfer id is the stable Horcrux replay key for this immutable request.
+      const signature = await settler.sign({
+        idempotencyKey: current.id,
+        prepared: result.prepared,
+      })
+      const persisted = await Transfer.signTronSubsidy(options.db, {
+        id: current.id,
+        signed: signature,
+      })
+      if (persisted.type === 'not_found' || persisted.type === 'invalid') return { type: 'pending' }
+      signed = persisted.signed
+      current = persisted.record
+      if ('references' in persisted && options.dispatchTransferUpdates)
+        await options.dispatchTransferUpdates(persisted.references)
+      options.recordSubsidy(persisted.type === 'shared' ? 'shared' : 'signed')
+    }
+  }
+  const status = await settler.status({
+    chain: options.destinationChain,
+    recipient,
+    signed,
+    token,
+  })
+  if (status === 'reverted') {
+    options.recordSubsidy('reverted')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'The destination subsidy transaction reverted.',
+      },
+      record: current,
+      state: {
+        subsidyAmount: Value.tokenAmount({
+          baseUnits: 0n,
+          currency: current.snapshot.destinationToken.currency,
+          decimals: current.snapshot.destinationToken.decimals,
+        }),
+      },
+      type: 'action-required',
+    }
+  }
+  if (status === 'pending') {
+    if (signed.expiresAt + tronFinalityGraceMs <= Date.now()) {
+      options.recordSubsidy('expired')
+      return {
+        reason: {
+          code: 'subsidy_failed',
+          message: 'The Tron subsidy expired without verified delivery.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    // An included transaction may remain invisible to the solidified RPC after its TAPOS expiry.
+    if (signed.expiresAt <= Date.now()) return { type: 'pending' }
+    const rejected = await settler.broadcast({ chain: options.destinationChain, signed }).then(
+      () => false,
+      (cause: unknown) => {
+        if (TronTransferSubsidy.isPermanentBroadcastError(cause)) return true
+        throw cause
+      },
+    )
+    if (rejected) {
+      options.recordSubsidy('broadcast_rejected')
+      return {
+        reason: {
+          code: 'subsidy_failed',
+          message: 'The Tron subsidy transaction was rejected.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    options.recordSubsidy('broadcast')
+    return { type: 'pending' }
+  }
+  options.recordSubsidy('completed')
+  return { amount: options.deficit, hash: signed.hash, record: current, type: 'success' }
+}
+
+export declare namespace settle {
+  /** Dependencies for one Tron settlement attempt. */
+  type Options = TransferSettlement.Options & {
+    /** Available Horcrux-managed Tron wallets. */
+    settlers?: readonly TronTransferSubsidy.Settler[] | undefined
+  }
+}

package/src/internal/routes/TronTransferSubsidy.test.ts

@@ -0,0 +1,109 @@
+import { AbiFunction, Address, Hash, Secp256k1, Signature } from 'ox'
+
+import * as Tron from '../Tron.js'
+import * as Subsidy from './TronTransferSubsidy.js'
+
+const transfer = AbiFunction.from('function transfer(address to, uint256 amount) returns (bool)')
+const recipient = Tron.fromEvmAddress('0x1111111111111111111111111111111111111111')
+const token = Tron.fromEvmAddress('0x2222222222222222222222222222222222222222')
+
+function fixture() {
+  const { privateKey, publicKey } = Secp256k1.createKeyPair()
+  const account = Tron.fromEvmAddress(Address.fromPublicKey(publicKey))
+  const rawDataHex = '010203'
+  const hash = Hash.sha256(`0x${rawDataHex}`)
+  const data = AbiFunction.encodeData(transfer, [Tron.toEvmAddress(recipient), 100n]).slice(2)
+  const owner_address = `41${Tron.toEvmAddress(account).slice(2)}`
+  const contract_address = `41${Tron.toEvmAddress(token).slice(2)}`
+  const raw_data = {
+    contract: [
+      { contract_address, data, owner_address, type: 'TriggerSmartContract' as const },
+    ] as const,
+    expiration: 1_735_689_600_000,
+    fee_limit: 100_000_000,
+    ref_block_bytes: 'a2b4',
+    ref_block_hash: '1234567890abcdef',
+    timestamp: 1_735_689_540_000,
+  }
+  const prepared = {
+    account,
+    amount: '100',
+    chainId: 'tron:0x2b6653dc',
+    expiresAt: raw_data.expiration,
+    hash,
+    nativeAmount: String(raw_data.fee_limit),
+    rawDataHex,
+    request: { network: 'tron:mainnet' as const, transaction: { raw_data } },
+    transaction: { raw_data, raw_data_hex: rawDataHex, txID: hash.slice(2) },
+  }
+  const signature = Signature.toHex(Secp256k1.sign({ payload: hash, privateKey })).slice(2)
+  return { prepared, signature }
+}
+
+describe('readPrepared', () => {
+  test('accepts an immutable Tron transfer and rejects changed amount or raw bytes', () => {
+    const { prepared } = fixture()
+    expect(Subsidy.readPrepared(prepared)).toEqual(prepared)
+    expect(Subsidy.readPrepared(JSON.stringify(prepared))).toEqual(prepared)
+    expect(Subsidy.readPrepared({ ...prepared, amount: '101' })).toBeUndefined()
+    expect(Subsidy.readPrepared({ ...prepared, rawDataHex: '010204' })).toBeUndefined()
+  })
+})
+
+describe('readSigned', () => {
+  test('requires a recoverable signature from the prepared subsidy wallet', () => {
+    const { prepared, signature } = fixture()
+    expect(Subsidy.readSigned({ ...prepared, signature })).toEqual({ ...prepared, signature })
+    expect(Subsidy.readSigned(JSON.stringify({ ...prepared, signature }))).toEqual({
+      ...prepared,
+      signature,
+    })
+    expect(Subsidy.readSigned({ ...prepared, signature: '00'.repeat(65) })).toBeUndefined()
+  })
+})
+
+describe('matchesTerms', () => {
+  test('checks the exact destination wallet, token, recipient, amount, and chain', () => {
+    const { prepared } = fixture()
+    const terms = {
+      account: prepared.account,
+      amount: 100n,
+      chainId: prepared.chainId,
+      recipient,
+      token,
+    }
+    expect(Subsidy.matchesTerms(prepared, terms)).toBe(true)
+    expect(Subsidy.matchesTerms(prepared, { ...terms, amount: 101n })).toBe(false)
+    expect(Subsidy.matchesTerms(prepared, { ...terms, recipient: token })).toBe(false)
+    expect(Subsidy.matchesTerms(prepared, { ...terms, token: recipient })).toBe(false)
+    expect(Subsidy.matchesTerms(prepared, { ...terms, chainId: 'tron:nile' })).toBe(false)
+  })
+})
+
+describe('isPermanentBroadcastError', () => {
+  test('recognizes deterministic rejections while keeping transient failures retryable', () => {
+    expect(
+      Subsidy.isPermanentBroadcastError(new Subsidy.BroadcastError('Rejected.', 'SIGERROR')),
+    ).toBe(true)
+    expect(
+      Subsidy.isPermanentBroadcastError(new Subsidy.BroadcastError('Retry later.', 'SERVER_BUSY')),
+    ).toBe(false)
+  })
+})
+
+describe('create', () => {
+  test('rejects invalid signer configuration before chain access', () => {
+    expect(() =>
+      Subsidy.create({
+        account: 'not-a-Tron-address',
+        feeLimitSun: 100_000_000,
+        fetch,
+        horcrux: { auth: { type: 'none' }, url: 'http://127.0.0.1:3040' },
+        policy: { maxAmount: '0.10' },
+        walletId: 'a709a198-4726-4a43-b7c3-2f4e6100f9b8',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      '[Routes.TronTransferSubsidy.ConfigurationError: Invalid Tron subsidy account.]',
+    )
+  })
+})