tapimo 0.15.1 → 0.18.1

package/src/internal/routes/SolanaTransferSubsidy.ts

@@ -0,0 +1,760 @@
+import { ed25519 } from '@noble/curves/ed25519'
+import {
+  findAssociatedTokenPda,
+  getTokenDecoder,
+  getTransferCheckedInstruction,
+  TOKEN_PROGRAM_ADDRESS,
+} from '@solana-program/token'
+import {
+  address,
+  appendTransactionMessageInstruction,
+  blockhash,
+  compileTransaction,
+  createTransactionMessage,
+  decompileTransactionMessage,
+  getCompiledTransactionMessageDecoder,
+  getTransactionDecoder,
+  getTransactionEncoder,
+  setTransactionMessageFeePayer,
+  setTransactionMessageLifetimeUsingBlockhash,
+} from '@solana/kit'
+import { Base58 } from 'ox'
+
+import type * as Chain from './Chain.js'
+
+const mainnet = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
+const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+const recoverySlotWindow = 256
+const signingBlockMargin = 64
+
+/** An immutable Solana transaction prepared before requesting a Horcrux signature. */
+export type Prepared = {
+  /** Horcrux wallet public key. */
+  account: string
+  /** Destination token quantity in base units. */
+  amount: string
+  /** Destination chain identifier. */
+  chainId: string
+  /** Derived recipient USDC token account. */
+  destination: string
+  /** Last block height at which Solana accepts the transaction. */
+  lastValidBlockHeight: number
+  /** Native SOL fee reserved in lamports. */
+  nativeAmount: string
+  /** Finalized slot that supplied the transaction blockhash. */
+  originSlot: number
+  /** Recipient wallet public key. */
+  recipient: string
+  /** Exact body sent to Horcrux on signing retries. */
+  request: { network: 'solana:mainnet-beta'; transaction: string }
+  /** Derived subsidy wallet USDC token account. */
+  source: string
+  /** Destination token mint. */
+  token: string
+}
+
+/** A Horcrux-signed transaction persisted before broadcast. */
+export type Signed = Prepared & {
+  /** First Solana signature, used as the transaction identifier. */
+  hash: string
+  /** Canonical signed transaction in standard base64. */
+  transaction: string
+}
+
+/** Read-only Solana destination subsidy inventory checker. */
+export type Inventory = {
+  /** Horcrux wallet public key. */
+  account: string
+  /** Checks USDC and SOL capacity including unsettled commitments. */
+  check(options: create.CheckOptions): Promise<{ nativeAmount: string }>
+  /** Operational maximum destination subsidy. */
+  policy: { maxAmount: string }
+}
+
+/** Prepares, signs, broadcasts, and verifies Solana destination subsidies. */
+export type Settler = Inventory & {
+  /** Broadcasts the persisted signed transaction. */
+  broadcast(options: { chain: Chain.Chain; signed: Signed }): Promise<void>
+  /** Checks whether a prepared blockhash is too close to expiry to sign safely. */
+  expiring(options: { chain: Chain.Chain; prepared: Prepared }): Promise<boolean>
+  /** Constructs an unsigned transfer without contacting Horcrux. */
+  prepare(options: create.CheckOptions): Promise<Prepared>
+  /** Signs an immutable request through Horcrux. */
+  sign(options: { idempotencyKey: string; prepared: Prepared }): Promise<Signed>
+  /** Reads finalized execution for the exact signed transaction. */
+  status(
+    options: create.StatusOptions,
+  ): Promise<'ambiguous' | 'expired' | 'pending' | 'reverted' | 'success'>
+}
+
+/** Validates prepared subsidy state restored from durable storage. */
+export function readPrepared(value: unknown): Prepared | undefined {
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value)
+    } catch {
+      return undefined
+    }
+  }
+  if (!isObject(value) || !isObject(value['request'])) return undefined
+  const request = value['request']
+  if (
+    typeof value['account'] !== 'string' ||
+    typeof value['amount'] !== 'string' ||
+    !/^[1-9]\d*$/.test(value['amount']) ||
+    value['chainId'] !== mainnet ||
+    typeof value['destination'] !== 'string' ||
+    typeof value['lastValidBlockHeight'] !== 'number' ||
+    !Number.isSafeInteger(value['lastValidBlockHeight']) ||
+    value['lastValidBlockHeight'] <= 0 ||
+    typeof value['nativeAmount'] !== 'string' ||
+    !/^[1-9]\d*$/.test(value['nativeAmount']) ||
+    typeof value['originSlot'] !== 'number' ||
+    !Number.isSafeInteger(value['originSlot']) ||
+    value['originSlot'] <= 0 ||
+    typeof value['recipient'] !== 'string' ||
+    typeof value['source'] !== 'string' ||
+    value['token'] !== usdcMint ||
+    request['network'] !== 'solana:mainnet-beta' ||
+    typeof request['transaction'] !== 'string'
+  )
+    return undefined
+  try {
+    const account = address(value['account'])
+    address(value['recipient'])
+    const source = address(value['source'])
+    const destination = address(value['destination'])
+    const raw = Buffer.from(request['transaction'], 'base64')
+    if (raw.toString('base64') !== request['transaction']) return undefined
+    const tx = getTransactionDecoder().decode(raw)
+    const compiled = getCompiledTransactionMessageDecoder().decode(tx.messageBytes)
+    if (compiled.version !== 'legacy') return undefined
+    const message = decompileTransactionMessage(compiled)
+    if (!('blockhash' in message.lifetimeConstraint)) return undefined
+    if (Object.keys(tx.signatures).length !== 1 || tx.signatures[account] !== null) return undefined
+    const expected = unsignedTransaction({
+      account,
+      amount: BigInt(value['amount']),
+      blockhash: message.lifetimeConstraint.blockhash,
+      destination,
+      source,
+    })
+    if (!Buffer.from(getTransactionEncoder().encode(expected)).equals(raw)) return undefined
+  } catch {
+    return undefined
+  }
+  return value as Prepared
+}
+
+/** Validates signed subsidy state restored from durable storage. */
+export function readSigned(value: unknown): Signed | undefined {
+  const prepared = readPrepared(value)
+  if (!prepared || typeof (prepared as Signed).transaction !== 'string') return undefined
+  const signed = prepared as Signed
+  try {
+    const raw = Buffer.from(signed.transaction, 'base64')
+    if (raw.toString('base64') !== signed.transaction) return undefined
+    const tx = getTransactionDecoder().decode(raw)
+    const signature = tx.signatures[address(signed.account)]
+    const preparedTransaction = getTransactionDecoder().decode(
+      Buffer.from(prepared.request.transaction, 'base64'),
+    )
+    if (
+      typeof signed.hash !== 'string' ||
+      !signature ||
+      Object.keys(tx.signatures).length !== 1 ||
+      !Buffer.from(tx.messageBytes).equals(Buffer.from(preparedTransaction.messageBytes)) ||
+      !ed25519.verify(
+        Buffer.from(signature),
+        Buffer.from(tx.messageBytes),
+        Base58.toBytes(signed.account),
+      ) ||
+      Base58.fromBytes(signature) !== signed.hash ||
+      !Buffer.from(getTransactionEncoder().encode(tx)).equals(raw)
+    )
+      return undefined
+  } catch {
+    return undefined
+  }
+  return signed
+}
+
+/** Checks persisted transaction terms against freshly verified delivery. */
+export function matchesTerms(prepared: Prepared, options: matchesTerms.Options): boolean {
+  return (
+    readPrepared(prepared) !== undefined &&
+    prepared.account === options.account &&
+    prepared.amount === options.amount.toString() &&
+    prepared.chainId === options.chainId &&
+    prepared.recipient === options.recipient &&
+    prepared.token === options.token
+  )
+}
+
+export declare namespace matchesTerms {
+  /** Exact terms required before a subsidy is signed or broadcast. */
+  type Options = {
+    account: string
+    amount: bigint
+    chainId: string
+    recipient: string
+    token: string
+  }
+}
+
+/** Creates a Solana inventory checker and Horcrux signer for one wallet. */
+export function create(options: create.Options): Settler {
+  const account = address(options.account)
+  if (!/^[0-9a-fA-F-]{36}$/.test(options.walletId))
+    throw new ConfigurationError('Invalid Horcrux wallet ID.')
+  const horcruxUrl = new URL(options.horcrux.url)
+  if (
+    !['https:', 'http:'].includes(horcruxUrl.protocol) ||
+    (horcruxUrl.protocol === 'http:' &&
+      !['localhost', '127.0.0.1', '[::1]'].includes(horcruxUrl.hostname)) ||
+    horcruxUrl.username ||
+    horcruxUrl.password ||
+    horcruxUrl.search ||
+    horcruxUrl.hash
+  )
+    throw new ConfigurationError('Horcrux requires HTTPS or loopback HTTP.')
+  if (
+    options.horcrux.auth.type === 'none' &&
+    !['localhost', '127.0.0.1', '[::1]'].includes(horcruxUrl.hostname)
+  )
+    throw new ConfigurationError('Unauthenticated Horcrux requires loopback.')
+
+  async function rpc(chain: Chain.Chain, method: string, params: readonly unknown[]) {
+    assertChain(chain)
+    let failure: UpstreamError | undefined
+    for (const url of chain.rpcUrls) {
+      let response: Response
+      try {
+        response = await options.fetch(url, {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method, params }),
+          headers: { 'content-type': 'application/json' },
+          method: 'POST',
+          signal: AbortSignal.timeout(10_000),
+        })
+      } catch {
+        failure = new UpstreamError(`Solana RPC ${method} is unavailable.`)
+        continue
+      }
+      if (!response.ok) {
+        failure = new UpstreamError(`Solana RPC returned HTTP ${response.status}.`)
+        continue
+      }
+      let body: unknown
+      try {
+        body = await response.json()
+      } catch {
+        failure = new UpstreamError(`Solana RPC ${method} returned an invalid response.`)
+        continue
+      }
+      if (!isObject(body)) {
+        failure = new UpstreamError(`Solana RPC ${method} returned an invalid response.`)
+        continue
+      }
+      if (body['error'] !== undefined) {
+        const cause = body['error']
+        const message =
+          isObject(cause) && typeof cause['message'] === 'string'
+            ? cause['message']
+            : 'unknown error'
+        const blockhashNotFound =
+          isObject(cause) &&
+          ((isObject(cause['data']) && cause['data']['err'] === 'BlockhashNotFound') ||
+            /blockhash not found/i.test(message))
+        const error = new UpstreamError(`Solana RPC ${method} failed: ${message}`)
+        // Other nodes may still serve a request when one node is unhealthy or lacks recent history.
+        if (
+          isObject(cause) &&
+          typeof cause['code'] === 'number' &&
+          ([-32603, -32016, -32009, -32005, -32004].includes(cause['code']) ||
+            (method === 'sendTransaction' && cause['code'] === -32002 && blockhashNotFound))
+        ) {
+          failure = error
+          continue
+        }
+        throw error
+      }
+      if (!('result' in body)) {
+        failure = new UpstreamError(`Solana RPC ${method} omitted a result.`)
+        continue
+      }
+      return body['result']
+    }
+    throw failure ?? new UpstreamError(`Solana RPC ${method} is unavailable.`)
+  }
+
+  async function expiredStatus(chain: Chain.Chain, signed: Signed) {
+    const info = await rpc(chain, 'getEpochInfo', [{ commitment: 'finalized' }])
+    if (
+      !isObject(info) ||
+      typeof info['absoluteSlot'] !== 'number' ||
+      typeof info['blockHeight'] !== 'number' ||
+      !Number.isSafeInteger(info['absoluteSlot']) ||
+      !Number.isSafeInteger(info['blockHeight'])
+    )
+      throw new UpstreamError('Solana finalized position is unavailable.')
+    if (info['blockHeight'] <= signed.lastValidBlockHeight) return 'pending' as const
+    const endSlot = info['absoluteSlot']
+    if (endSlot < signed.originSlot) return 'ambiguous' as const
+    const first = await rpc(chain, 'getFirstAvailableBlock', [])
+    if (typeof first !== 'number' || !Number.isSafeInteger(first))
+      throw new UpstreamError('Solana block history boundary is unavailable.')
+    if (first > signed.originSlot) return 'ambiguous' as const
+    let previousSlot: number | undefined
+    let previousBlockhash: string | undefined
+    let previousHeight: number | undefined
+    for (let start = signed.originSlot; start <= endSlot; start += recoverySlotWindow) {
+      const end = Math.min(start + recoverySlotWindow - 1, endSlot)
+      const slots = await rpc(chain, 'getBlocks', [start, end, { commitment: 'finalized' }])
+      if (
+        !Array.isArray(slots) ||
+        slots.some(
+          (slot, index) =>
+            typeof slot !== 'number' ||
+            !Number.isSafeInteger(slot) ||
+            slot < start ||
+            slot > end ||
+            (index > 0 && slot <= slots[index - 1]),
+        )
+      )
+        return 'ambiguous' as const
+      for (let offset = 0; offset < slots.length; offset += 8) {
+        const batch = slots.slice(offset, offset + 8)
+        const blocks = await Promise.all(
+          batch.map((slot) =>
+            rpc(chain, 'getBlock', [
+              slot,
+              {
+                commitment: 'finalized',
+                maxSupportedTransactionVersion: 1,
+                rewards: false,
+                transactionDetails: 'signatures',
+              },
+            ]),
+          ),
+        )
+        for (const [index, block] of blocks.entries()) {
+          const slot = batch[index]!
+          const result = inspectFinalizedBlock({
+            block,
+            lastValidBlockHeight: signed.lastValidBlockHeight,
+            originSlot: signed.originSlot,
+            previousBlockhash,
+            previousHeight,
+            previousSlot,
+            signature: signed.hash,
+            slot,
+          })
+          if (result.type === 'ambiguous') return 'ambiguous' as const
+          previousSlot = slot
+          previousBlockhash = result.blockhash
+          previousHeight = result.blockHeight
+          if (result.type === 'found') {
+            const full = await rpc(chain, 'getBlock', [
+              slot,
+              {
+                commitment: 'finalized',
+                encoding: 'json',
+                maxSupportedTransactionVersion: 1,
+                rewards: false,
+                transactionDetails: 'full',
+              },
+            ])
+            if (
+              !isObject(full) ||
+              full['blockhash'] !== result.blockhash ||
+              !Array.isArray(full['transactions'])
+            )
+              return 'ambiguous' as const
+            const entry = full['transactions'].find(
+              (value) =>
+                isObject(value) &&
+                isObject(value['transaction']) &&
+                Array.isArray(value['transaction']['signatures']) &&
+                value['transaction']['signatures'].includes(signed.hash),
+            )
+            if (!isObject(entry) || !isObject(entry['meta']) || !('err' in entry['meta']))
+              return 'ambiguous' as const
+            return entry['meta']['err'] === null ? ('success' as const) : ('reverted' as const)
+          }
+          // The first finalized block above the validity height closes the entire inclusion window.
+          if (result.type === 'expired') return 'expired' as const
+        }
+      }
+    }
+    return 'ambiguous' as const
+  }
+
+  async function accountsMatch(prepared: Prepared) {
+    const mint = address(prepared.token)
+    const [[source], [destination]] = await Promise.all([
+      findAssociatedTokenPda({
+        mint,
+        owner: address(prepared.account),
+        tokenProgram: TOKEN_PROGRAM_ADDRESS,
+      }),
+      findAssociatedTokenPda({
+        mint,
+        owner: address(prepared.recipient),
+        tokenProgram: TOKEN_PROGRAM_ADDRESS,
+      }),
+    ])
+    return prepared.source === source && prepared.destination === destination
+  }
+
+  async function tokenAccount(chain: Chain.Chain, tokenAddress: string) {
+    const result = await rpc(chain, 'getAccountInfo', [
+      tokenAddress,
+      { commitment: 'finalized', encoding: 'base64' },
+    ])
+    if (!isObject(result) || !isObject(result['value'])) throw new BalanceUnavailableError()
+    const value = result['value']
+    if (
+      value['owner'] !== TOKEN_PROGRAM_ADDRESS ||
+      !Array.isArray(value['data']) ||
+      typeof value['data'][0] !== 'string' ||
+      value['data'][1] !== 'base64'
+    )
+      throw new ConfigurationError('Solana subsidy token account is invalid.')
+    return getTokenDecoder().decode(Buffer.from(value['data'][0], 'base64'))
+  }
+
+  async function construct(parameters: create.CheckOptions, requireDestination: boolean) {
+    assertChain(parameters.chain)
+    if (parameters.token !== usdcMint)
+      throw new ConfigurationError('Unsupported Solana subsidy token.')
+    const mint = address(parameters.token)
+    const recipient = address(parameters.recipient)
+    const [[source], [destination]] = await Promise.all([
+      findAssociatedTokenPda({ mint, owner: account, tokenProgram: TOKEN_PROGRAM_ADDRESS }),
+      findAssociatedTokenPda({ mint, owner: recipient, tokenProgram: TOKEN_PROGRAM_ADDRESS }),
+    ])
+    const [sourceAccount, destinationAccount, balanceResult, latestResult] = await Promise.all([
+      tokenAccount(parameters.chain, source),
+      requireDestination ? tokenAccount(parameters.chain, destination) : Promise.resolve(undefined),
+      rpc(parameters.chain, 'getBalance', [account, { commitment: 'finalized' }]),
+      rpc(parameters.chain, 'getLatestBlockhash', [{ commitment: 'finalized' }]),
+    ])
+    if (
+      !isObject(balanceResult) ||
+      typeof balanceResult['value'] !== 'number' ||
+      !isObject(latestResult) ||
+      !isObject(latestResult['value']) ||
+      typeof latestResult['value']['blockhash'] !== 'string' ||
+      typeof latestResult['value']['lastValidBlockHeight'] !== 'number' ||
+      !isObject(latestResult['context']) ||
+      typeof latestResult['context']['slot'] !== 'number' ||
+      !Number.isSafeInteger(latestResult['context']['slot']) ||
+      latestResult['context']['slot'] <= 0
+    )
+      throw new UpstreamError('Solana balance or blockhash is unavailable.')
+    const latest = latestResult['value']
+    if (
+      sourceAccount.owner !== account ||
+      sourceAccount.mint !== mint ||
+      (destinationAccount !== undefined &&
+        (destinationAccount.owner !== recipient || destinationAccount.mint !== mint))
+    )
+      throw new ConfigurationError('Solana subsidy token account terms changed.')
+    if (sourceAccount.amount < parameters.amount + parameters.reservations.tokenAmount)
+      throw new BalanceUnavailableError()
+    const tx = unsignedTransaction({
+      account,
+      amount: parameters.amount,
+      blockhash: blockhash(latest['blockhash'] as string),
+      destination,
+      source,
+    })
+    const feeResult = await rpc(parameters.chain, 'getFeeForMessage', [
+      Buffer.from(tx.messageBytes).toString('base64'),
+      { commitment: 'finalized' },
+    ])
+    if (!isObject(feeResult) || typeof feeResult['value'] !== 'number' || feeResult['value'] <= 0)
+      throw new UpstreamError('Solana fee is unavailable.')
+    const fee = feeResult['value']
+    if (BigInt(balanceResult['value']) < BigInt(fee) + parameters.reservations.nativeAmount)
+      throw new BalanceUnavailableError()
+    return {
+      destination,
+      fee,
+      latest,
+      originSlot: latestResult['context']['slot'] as number,
+      source,
+      tx,
+    }
+  }
+
+  return {
+    account,
+    async broadcast({ chain, signed }) {
+      if (!readSigned(signed) || signed.account !== account || !(await accountsMatch(signed)))
+        throw new ConfigurationError('Invalid signed Solana subsidy transaction.')
+      const hash = await rpc(chain, 'sendTransaction', [
+        signed.transaction,
+        { encoding: 'base64' },
+      ]).catch((cause) => {
+        if (cause instanceof Error && /already processed|duplicate signature/i.test(cause.message))
+          return signed.hash
+        throw cause
+      })
+      if (hash !== signed.hash) throw new BroadcastError('Solana returned a different signature.')
+    },
+    async check(parameters) {
+      const { fee } = await construct(parameters, false)
+      return { nativeAmount: String(fee) }
+    },
+    async expiring({ chain, prepared }) {
+      assertChain(chain)
+      if (!readPrepared(prepared) || prepared.chainId !== chain.id)
+        throw new ConfigurationError('Invalid prepared Solana subsidy transaction.')
+      const height = await rpc(chain, 'getBlockHeight', [{ commitment: 'confirmed' }])
+      if (typeof height !== 'number' || !Number.isSafeInteger(height) || height < 0)
+        throw new UpstreamError('Solana block height is unavailable.')
+      // Leave time for Horcrux signing, persistence, and the first broadcast.
+      return height + signingBlockMargin >= prepared.lastValidBlockHeight
+    },
+    policy: options.policy,
+    async prepare(parameters) {
+      const { destination, fee, latest, originSlot, source, tx } = await construct(parameters, true)
+      return {
+        account,
+        amount: parameters.amount.toString(),
+        chainId: parameters.chain.id,
+        destination,
+        lastValidBlockHeight: latest['lastValidBlockHeight'] as number,
+        nativeAmount: String(fee),
+        originSlot,
+        recipient: parameters.recipient,
+        request: {
+          network: 'solana:mainnet-beta',
+          transaction: Buffer.from(getTransactionEncoder().encode(tx)).toString('base64'),
+        },
+        source,
+        token: parameters.token,
+      }
+    },
+    async sign({ idempotencyKey, prepared }) {
+      if (!/^[\x21-\x7e]{1,256}$/.test(idempotencyKey))
+        throw new ConfigurationError('Invalid Horcrux idempotency key.')
+      if (
+        !readPrepared(prepared) ||
+        prepared.account !== account ||
+        !(await accountsMatch(prepared))
+      )
+        throw new ConfigurationError('Invalid prepared Solana subsidy transaction.')
+      const headers: Record<string, string> = {
+        'content-type': 'application/json',
+        'Idempotency-Key': idempotencyKey,
+      }
+      if (options.horcrux.auth.type === 'cloudflare-access') {
+        headers['CF-Access-Client-Id'] = options.horcrux.auth.clientId
+        headers['CF-Access-Client-Secret'] = options.horcrux.auth.clientSecret
+      }
+      const response = await options.fetch(
+        new URL(`/v1/wallets/${options.walletId}/sign`, horcruxUrl),
+        {
+          body: JSON.stringify(prepared.request),
+          headers,
+          method: 'POST',
+          redirect: 'manual',
+          signal: AbortSignal.timeout(10_000),
+        },
+      )
+      if (!response.ok) throw new SigningError(`Horcrux signing returned HTTP ${response.status}.`)
+      const result: unknown = await response.json()
+      if (!isObject(result) || typeof result['signed_transaction'] !== 'string')
+        throw new SigningError('Horcrux returned an invalid signing response.')
+      const tx = getTransactionDecoder().decode(Buffer.from(result['signed_transaction'], 'base64'))
+      const signature = tx.signatures[address(account)]
+      if (!signature) throw new SigningError('Horcrux omitted the Solana signature.')
+      const signed = {
+        ...prepared,
+        hash: Base58.fromBytes(signature),
+        transaction: result['signed_transaction'],
+      }
+      if (!readSigned(signed)) throw new SigningError('Horcrux changed the Solana transaction.')
+      return signed
+    },
+    async status({ chain, recipient, signed, token }) {
+      if (
+        !readSigned(signed) ||
+        !(await accountsMatch(signed)) ||
+        !matchesTerms(signed, {
+          account,
+          amount: BigInt(signed.amount),
+          chainId: chain.id,
+          recipient,
+          token,
+        })
+      )
+        return 'reverted'
+      const result = await rpc(chain, 'getSignatureStatuses', [
+        [signed.hash],
+        { searchTransactionHistory: true },
+      ])
+      if (!isObject(result) || !Array.isArray(result['value']))
+        throw new UpstreamError('Solana signature status is unavailable.')
+      const receipt = result['value'][0]
+      if (!receipt) return expiredStatus(chain, signed)
+      if (!isObject(receipt)) throw new UpstreamError('Solana signature status is invalid.')
+      if (receipt['confirmationStatus'] !== 'finalized') return 'pending'
+      return receipt['err'] ? 'reverted' : 'success'
+    },
+  }
+}
+
+export declare namespace create {
+  /** Horcrux connection and Solana RPC dependencies. */
+  type Options = {
+    account: string
+    fetch: typeof globalThis.fetch
+    horcrux: {
+      auth: { type: 'none' } | { clientId: string; clientSecret: string; type: 'cloudflare-access' }
+      url: string
+    }
+    policy: { maxAmount: string }
+    walletId: string
+  }
+
+  /** Creation-time inventory request. */
+  type CheckOptions = {
+    amount: bigint
+    chain: Chain.Chain
+    recipient: string
+    reservations: { nativeAmount: bigint; tokenAmount: bigint }
+    token: string
+  }
+
+  /** Finalized receipt query and expected delivery. */
+  type StatusOptions = { chain: Chain.Chain; recipient: string; signed: Signed; token: string }
+}
+
+/** Checks one finalized block against the signed transaction and the preceding block. */
+export function inspectFinalizedBlock(
+  options: inspectFinalizedBlock.Options,
+):
+  | { type: 'ambiguous' }
+  | { blockhash: string; blockHeight: number; type: 'absent' | 'expired' | 'found' } {
+  const block = options.block
+  if (
+    !isObject(block) ||
+    typeof block['blockhash'] !== 'string' ||
+    typeof block['previousBlockhash'] !== 'string' ||
+    typeof block['parentSlot'] !== 'number' ||
+    !Number.isSafeInteger(block['parentSlot']) ||
+    typeof block['blockHeight'] !== 'number' ||
+    !Number.isSafeInteger(block['blockHeight']) ||
+    !Array.isArray(block['signatures']) ||
+    !block['signatures'].every((signature) => typeof signature === 'string') ||
+    (options.previousSlot === undefined && options.slot !== options.originSlot) ||
+    (options.previousSlot !== undefined &&
+      (block['parentSlot'] !== options.previousSlot ||
+        block['previousBlockhash'] !== options.previousBlockhash ||
+        options.previousHeight === undefined ||
+        block['blockHeight'] !== options.previousHeight + 1))
+  )
+    return { type: 'ambiguous' }
+  const blockHeight = block['blockHeight']
+  const type = (() => {
+    if (block['signatures'].includes(options.signature)) return 'found' as const
+    if (blockHeight > options.lastValidBlockHeight) return 'expired' as const
+    return 'absent' as const
+  })()
+  return {
+    blockhash: block['blockhash'],
+    blockHeight,
+    type,
+  }
+}
+
+export declare namespace inspectFinalizedBlock {
+  /** Finalized block and its expected place in a continuous chain. */
+  type Options = {
+    block: unknown
+    lastValidBlockHeight: number
+    originSlot: number
+    previousBlockhash: string | undefined
+    previousHeight: number | undefined
+    previousSlot: number | undefined
+    signature: string
+    slot: number
+  }
+}
+
+function assertChain(chain: Chain.Chain) {
+  if (chain.id !== mainnet || chain.kind !== 'solana' || chain.rpcUrls.length === 0)
+    throw new ConfigurationError('Unsupported Solana subsidy chain.')
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function unsignedTransaction(options: unsignedTransaction.Options) {
+  const message = appendTransactionMessageInstruction(
+    getTransferCheckedInstruction({
+      amount: options.amount,
+      authority: options.account,
+      decimals: 6,
+      destination: options.destination,
+      mint: address(usdcMint),
+      source: options.source,
+    }),
+    setTransactionMessageLifetimeUsingBlockhash(
+      { blockhash: options.blockhash, lastValidBlockHeight: 0n },
+      setTransactionMessageFeePayer(
+        options.account,
+        createTransactionMessage({ version: 'legacy' }),
+      ),
+    ),
+  )
+  return compileTransaction(message)
+}
+
+declare namespace unsignedTransaction {
+  type Options = {
+    account: ReturnType<typeof address>
+    amount: bigint
+    blockhash: ReturnType<typeof blockhash>
+    destination: ReturnType<typeof address>
+    source: ReturnType<typeof address>
+  }
+}
+
+/** Returns whether replaying the same signed transaction cannot succeed. */
+export function isPermanentBroadcastError(cause: unknown): boolean {
+  if (cause instanceof BroadcastError || cause instanceof ConfigurationError) return true
+  if (!(cause instanceof Error)) return false
+  return /block height exceeded|transaction expired|custom program error|invalid account data|signature verification failed/i.test(
+    cause.message,
+  )
+}
+
+/** The subsidy wallet lacks USDC or SOL inventory. */
+export class BalanceUnavailableError extends Error {
+  override name = 'Routes.SolanaTransferSubsidy.BalanceUnavailableError'
+}
+
+/** Solana subsidy configuration or persisted terms are invalid. */
+export class ConfigurationError extends Error {
+  override name = 'Routes.SolanaTransferSubsidy.ConfigurationError'
+}
+
+/** Horcrux failed to return the expected Solana signature. */
+export class SigningError extends Error {
+  override name = 'Routes.SolanaTransferSubsidy.SigningError'
+}
+
+/** Solana rejected a signed subsidy transaction. */
+export class BroadcastError extends Error {
+  override name = 'Routes.SolanaTransferSubsidy.BroadcastError'
+}
+
+/** Solana RPC could not provide reliable inventory or fee data. */
+export class UpstreamError extends Error {
+  override name = 'Routes.SolanaTransferSubsidy.UpstreamError'
+}