tapimo 0.15.1 → 0.18.0

package/src/internal/routes/TronTransferSubsidy.ts

@@ -0,0 +1,619 @@
+import { AbiFunction, Address, Hash, Hex, Secp256k1, Signature } from 'ox'
+import * as z from 'zod/mini'
+
+import * as Tron from '../Tron.js'
+import type * as Chain from './Chain.js'
+
+const balanceOf = AbiFunction.from('function balanceOf(address account) view returns (uint256)')
+const transfer = AbiFunction.from('function transfer(address to, uint256 amount) returns (bool)')
+const transferTopic = Hash.keccak256(Hex.fromString('Transfer(address,address,uint256)')).slice(2)
+const minimumPreparationWindowMs = 30_000
+
+namespace schema {
+  const address = z.string().check(z.regex(/^41[0-9a-fA-F]{40}$/))
+  const bytes = z.string().check(z.regex(/^(?:[0-9a-fA-F]{2})+$/))
+  const integer = z.number().check(z.int(), z.nonnegative(), z.maximum(Number.MAX_SAFE_INTEGER))
+
+  /** Native Tron transaction fields required for exact signing and broadcast. */
+  export const UnsignedTransaction = z
+    .object({
+      raw_data: z.object({
+        contract: z
+          .array(
+            z.object({
+              parameter: z.object({
+                value: z.object({
+                  call_value: z.optional(integer),
+                  contract_address: address,
+                  data: bytes,
+                  owner_address: address,
+                }),
+              }),
+              type: z.literal('TriggerSmartContract'),
+            }),
+          )
+          .check(z.minLength(1), z.maxLength(1)),
+        expiration: integer,
+        fee_limit: integer,
+        ref_block_bytes: z.string().check(z.regex(/^[0-9a-fA-F]{4}$/)),
+        ref_block_hash: z.string().check(z.regex(/^[0-9a-fA-F]{16}$/)),
+        timestamp: integer,
+      }),
+      raw_data_hex: bytes,
+      txID: z.string().check(z.regex(/^[0-9a-fA-F]{64}$/)),
+    })
+    .check(z.describe('Unsigned Tron smart-contract transaction.'))
+}
+
+/** An immutable Tron transaction prepared before requesting a Horcrux signature. */
+export type Prepared = {
+  /** Base58Check address of the destination subsidy wallet. */
+  account: string
+  /** Destination token amount supplied by Tempo. */
+  amount: string
+  /** Destination chain CAIP-2 identifier. */
+  chainId: string
+  /** Native TRX fee limit reserved in SUN. */
+  nativeAmount: string
+  /** Full node's unsigned transaction, retained for exact broadcast. */
+  transaction: Record<string, unknown>
+  /** Horcrux request body retained unchanged for ambiguous signing retries. */
+  request: {
+    network: 'tron:mainnet'
+    transaction: {
+      raw_data: {
+        contract: readonly [
+          {
+            contract_address: string
+            data: string
+            owner_address: string
+            type: 'TriggerSmartContract'
+          },
+        ]
+        expiration: number
+        fee_limit: number
+        ref_block_bytes: string
+        ref_block_hash: string
+        timestamp: number
+      }
+    }
+  }
+  /** SHA-256 of the exact raw protobuf bytes signed by Horcrux. */
+  hash: Hex.Hex
+  /** Unprefixed protobuf serialization of the prepared raw transaction. */
+  rawDataHex: string
+  /** Original Tron expiration in Unix milliseconds. */
+  expiresAt: number
+}
+
+/** A Horcrux-signed transaction, persisted before broadcast. */
+export type Signed = Prepared & {
+  /** Exact 65-byte secp256k1 signature returned by Horcrux. */
+  signature: string
+}
+
+/** Read-only destination inventory check for a Tron subsidy wallet. */
+export type Inventory = {
+  /** Base58Check subsidy wallet address. */
+  account: string
+  /** Verifies TRC-20 and TRX capacity including outstanding reservations. */
+  check: (options: create.CheckOptions) => Promise<{ nativeAmount: string }>
+  /** Operational maximum destination subsidy. */
+  policy: { maxAmount: string }
+}
+
+/** Prepares, signs, broadcasts, and verifies one Tron destination subsidy. */
+export type Settler = Inventory & {
+  /** Broadcasts exactly the persisted signed transaction. */
+  broadcast: (options: { chain: Chain.Chain; signed: Signed }) => Promise<void>
+  /** Constructs an unsigned transaction without contacting Horcrux. */
+  prepare: (options: create.PrepareOptions) => Promise<Prepared>
+  /** Signs a previously persisted immutable request through Horcrux. */
+  sign: (options: { idempotencyKey: string; prepared: Prepared }) => Promise<Signed>
+  /** Reads a solidified execution receipt and matching TRC-20 transfer log. */
+  status: (options: create.StatusOptions) => Promise<'pending' | 'reverted' | 'success'>
+}
+
+/** Validates an unsigned transaction restored from private route state. */
+export function readPrepared(value: unknown): Prepared | undefined {
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value)
+    } catch {
+      return undefined
+    }
+  }
+  if (!isObject(value)) return undefined
+  const request = value['request']
+  const transaction = value['transaction']
+  const raw =
+    isObject(request) && isObject(request['transaction'])
+      ? request['transaction']['raw_data']
+      : undefined
+  const contracts = isObject(raw) ? raw['contract'] : undefined
+  const contract = Array.isArray(contracts) ? contracts[0] : undefined
+  if (
+    typeof value['account'] !== 'string' ||
+    typeof value['amount'] !== 'string' ||
+    !/^\d+$/.test(value['amount']) ||
+    value['chainId'] !== 'tron:0x2b6653dc' ||
+    typeof value['nativeAmount'] !== 'string' ||
+    !/^[1-9]\d*$/.test(value['nativeAmount']) ||
+    !isObject(transaction) ||
+    !isObject(request) ||
+    request['network'] !== 'tron:mainnet' ||
+    !isObject(raw) ||
+    !Array.isArray(contracts) ||
+    contracts.length !== 1 ||
+    !isObject(contract) ||
+    contract['type'] !== 'TriggerSmartContract' ||
+    typeof contract['owner_address'] !== 'string' ||
+    typeof contract['contract_address'] !== 'string' ||
+    typeof contract['data'] !== 'string' ||
+    !/^41[0-9a-fA-F]{40}$/.test(contract['owner_address']) ||
+    !/^41[0-9a-fA-F]{40}$/.test(contract['contract_address']) ||
+    !/^(?:[0-9a-fA-F]{2})+$/.test(contract['data']) ||
+    typeof raw['ref_block_bytes'] !== 'string' ||
+    !/^[0-9a-fA-F]{4}$/.test(raw['ref_block_bytes']) ||
+    typeof raw['ref_block_hash'] !== 'string' ||
+    !/^[0-9a-fA-F]{16}$/.test(raw['ref_block_hash']) ||
+    typeof raw['timestamp'] !== 'number' ||
+    !Number.isSafeInteger(raw['timestamp']) ||
+    typeof raw['expiration'] !== 'number' ||
+    !Number.isSafeInteger(raw['expiration']) ||
+    raw['expiration'] <= raw['timestamp'] ||
+    value['expiresAt'] !== raw['expiration'] ||
+    typeof raw['fee_limit'] !== 'number' ||
+    !Number.isSafeInteger(raw['fee_limit']) ||
+    String(raw['fee_limit']) !== value['nativeAmount'] ||
+    typeof value['rawDataHex'] !== 'string' ||
+    !/^(?:[0-9a-fA-F]{2})+$/.test(value['rawDataHex']) ||
+    typeof value['hash'] !== 'string' ||
+    !/^0x[0-9a-fA-F]{64}$/.test(value['hash']) ||
+    transaction['raw_data_hex'] !== value['rawDataHex'] ||
+    typeof transaction['txID'] !== 'string' ||
+    transaction['txID'].toLowerCase() !== value['hash'].slice(2).toLowerCase()
+  )
+    return undefined
+  try {
+    if (
+      Tron.toEvmAddress(value['account']).slice(2).toLowerCase() !==
+      contract['owner_address'].slice(2).toLowerCase()
+    )
+      return undefined
+    if (Hash.sha256(`0x${value['rawDataHex']}`).toLowerCase() !== value['hash'].toLowerCase())
+      return undefined
+    const decoded = AbiFunction.decodeData(transfer, `0x${contract['data']}`)
+    if (decoded[1] !== BigInt(value['amount'])) return undefined
+  } catch {
+    return undefined
+  }
+  return value as Prepared
+}
+
+/** Validates a signed Tron transaction restored from private route state. */
+export function readSigned(value: unknown): Signed | undefined {
+  const prepared = readPrepared(value)
+  if (!prepared || typeof (prepared as Signed).signature !== 'string') return undefined
+  const signature = (prepared as Signed).signature
+  if (!/^[0-9a-fA-F]{130}$/.test(signature)) return undefined
+  try {
+    const recovered = Secp256k1.recoverAddress({
+      payload: prepared.hash,
+      signature: Signature.from(`0x${signature}`),
+    })
+    if (!Address.isEqual(recovered, Tron.toEvmAddress(prepared.account))) return undefined
+  } catch {
+    return undefined
+  }
+  return prepared as Signed
+}
+
+/** Checks a persisted Tron transaction against freshly verified transfer terms. */
+export function matchesTerms(prepared: Prepared, options: matchesTerms.Options): boolean {
+  if (
+    !readPrepared(prepared) ||
+    prepared.chainId !== options.chainId ||
+    prepared.account !== options.account ||
+    prepared.amount !== options.amount.toString()
+  )
+    return false
+  try {
+    const contract = prepared.request.transaction.raw_data.contract[0]
+    return (
+      contract.owner_address.toLowerCase() ===
+        `41${Tron.toEvmAddress(options.account).slice(2)}`.toLowerCase() &&
+      contract.contract_address.toLowerCase() ===
+        `41${Tron.toEvmAddress(options.token).slice(2)}`.toLowerCase() &&
+      contract.data.toLowerCase() ===
+        AbiFunction.encodeData(transfer, [Tron.toEvmAddress(options.recipient), options.amount])
+          .slice(2)
+          .toLowerCase()
+    )
+  } catch {
+    return false
+  }
+}
+
+export declare namespace matchesTerms {
+  /** Exact destination subsidy terms verified independently of the persisted request. */
+  type Options = {
+    /** Base58Check Tron subsidy wallet. */
+    account: string
+    /** Destination amount in token base units. */
+    amount: bigint
+    /** Destination chain CAIP-2 identifier. */
+    chainId: string
+    /** Base58Check recipient. */
+    recipient: string
+    /** Base58Check TRC-20 contract. */
+    token: string
+  }
+}
+
+/** Creates a Tron inventory checker and transaction signer for one Horcrux wallet. */
+export function create(options: create.Options): Settler {
+  if (!/^T[1-9A-HJ-NP-Za-km-z]{33}$/.test(options.account))
+    throw new ConfigurationError('Invalid Tron subsidy account.')
+  Tron.toEvmAddress(options.account)
+  if (!/^[0-9a-fA-F-]{36}$/.test(options.walletId))
+    throw new ConfigurationError('Invalid Horcrux wallet ID.')
+  if (!Number.isSafeInteger(options.feeLimitSun) || options.feeLimitSun <= 0)
+    throw new ConfigurationError('Invalid Tron fee limit.')
+  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 check(parameters: create.CheckOptions) {
+    assertChain(parameters.chain)
+    Tron.toEvmAddress(parameters.recipient)
+    Tron.toEvmAddress(parameters.token)
+    const client = Tron.createClient({ fetch: options.fetch, urls: parameters.chain.rpcUrls })
+    const balance = AbiFunction.decodeResult(
+      balanceOf,
+      await client.call({
+        data: AbiFunction.encodeData(balanceOf, [Tron.toEvmAddress(options.account)]),
+        to: parameters.token,
+      }),
+    )
+    if (balance < parameters.amount + parameters.reservations.tokenAmount)
+      throw new BalanceUnavailableError()
+    const account = await post(parameters.chain, 'wallet/getaccount', {
+      address: `41${Tron.toEvmAddress(options.account).slice(2)}`,
+      visible: false,
+    })
+    const nativeBalance = account['balance'] ?? 0
+    if (
+      typeof nativeBalance !== 'number' ||
+      !Number.isSafeInteger(nativeBalance) ||
+      nativeBalance < 0
+    )
+      throw new UpstreamError('Invalid Tron account balance.')
+    if (BigInt(nativeBalance) < BigInt(options.feeLimitSun) + parameters.reservations.nativeAmount)
+      throw new BalanceUnavailableError()
+    return { nativeAmount: String(options.feeLimitSun) }
+  }
+
+  async function prepare(parameters: create.PrepareOptions): Promise<Prepared> {
+    await check(parameters)
+    const data = AbiFunction.encodeData(transfer, [
+      Tron.toEvmAddress(parameters.recipient),
+      parameters.amount,
+    ]).slice(2)
+    const account = `41${Tron.toEvmAddress(options.account).slice(2)}`
+    const token = `41${Tron.toEvmAddress(parameters.token).slice(2)}`
+    const result = await post(parameters.chain, 'wallet/triggersmartcontract', {
+      contract_address: token,
+      data,
+      fee_limit: options.feeLimitSun,
+      owner_address: account,
+      visible: false,
+    })
+    const transaction = result['transaction']
+    if (
+      !isObject(result['result']) ||
+      result['result']['result'] !== true ||
+      !isObject(transaction)
+    )
+      throw new UpstreamError('Tron refused subsidy transaction construction.')
+    // Validate a parsed copy while retaining the node's original transaction for broadcast.
+    const parsed = schema.UnsignedTransaction.safeParse(transaction)
+    if (!parsed.success) throw new UpstreamError('Malformed unsigned Tron subsidy transaction.')
+    const { raw_data: raw, raw_data_hex: rawDataHex, txID: txId } = parsed.data
+    const value = raw.contract[0]!.parameter.value
+    if (
+      raw.fee_limit !== options.feeLimitSun ||
+      raw.timestamp <= 0 ||
+      // Signing is a separate durable step, so refuse node transactions nearly at expiry.
+      raw.expiration <= Date.now() + minimumPreparationWindowMs ||
+      raw.expiration <= raw.timestamp
+    )
+      throw new UpstreamError('Malformed unsigned Tron subsidy transaction.')
+    if (
+      value.owner_address.toLowerCase() !== account.toLowerCase() ||
+      value.contract_address.toLowerCase() !== token.toLowerCase() ||
+      value.data.toLowerCase() !== data.toLowerCase() ||
+      (value.call_value !== undefined && value.call_value !== 0)
+    )
+      throw new UpstreamError('Tron changed the subsidy transaction terms.')
+    const hash = Hash.sha256(`0x${rawDataHex}`)
+    if (hash.slice(2).toLowerCase() !== txId.toLowerCase())
+      throw new UpstreamError('Tron transaction hash does not match its raw bytes.')
+    return {
+      account: options.account,
+      amount: parameters.amount.toString(),
+      chainId: parameters.chain.id,
+      expiresAt: raw.expiration,
+      hash,
+      nativeAmount: String(options.feeLimitSun),
+      rawDataHex,
+      request: {
+        network: 'tron:mainnet',
+        transaction: {
+          raw_data: {
+            contract: [
+              {
+                contract_address: token,
+                data,
+                owner_address: account,
+                type: 'TriggerSmartContract',
+              },
+            ],
+            expiration: raw.expiration,
+            fee_limit: options.feeLimitSun,
+            ref_block_bytes: raw.ref_block_bytes,
+            ref_block_hash: raw.ref_block_hash,
+            timestamp: raw.timestamp,
+          },
+        },
+      },
+      transaction,
+    }
+  }
+
+  async function sign(parameters: { idempotencyKey: string; prepared: Prepared }): Promise<Signed> {
+    const { idempotencyKey, prepared } = parameters
+    if (!/^[\x21-\x7e]{1,256}$/.test(idempotencyKey))
+      throw new ConfigurationError('Invalid Horcrux idempotency key.')
+    if (prepared.account !== options.account || prepared.chainId !== 'tron:0x2b6653dc')
+      throw new ConfigurationError('Tron subsidy signer does not match the prepared 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 bytes = result['signed_transaction']
+    if (
+      !/^(?:[0-9a-fA-F]{2})+$/.test(bytes) ||
+      bytes.length !== prepared.rawDataHex.length + 130 ||
+      bytes.slice(0, prepared.rawDataHex.length).toLowerCase() !== prepared.rawDataHex.toLowerCase()
+    )
+      throw new SigningError('Horcrux changed the signed Tron transaction.')
+    const signature = bytes.slice(-130)
+    const recovered = Secp256k1.recoverAddress({
+      payload: prepared.hash,
+      signature: Signature.from(`0x${signature}`),
+    })
+    if (!Address.isEqual(recovered, Tron.toEvmAddress(options.account)))
+      throw new SigningError('Horcrux signature does not belong to the subsidy wallet.')
+    return { ...prepared, signature }
+  }
+
+  async function broadcast(parameters: { chain: Chain.Chain; signed: Signed }): Promise<void> {
+    assertChain(parameters.chain)
+    const { signed } = parameters
+    const result = await post(parameters.chain, 'wallet/broadcasttransaction', {
+      ...signed.transaction,
+      signature: [signed.signature],
+    })
+    const code =
+      result['code'] ?? (isObject(result['result']) ? result['result']['code'] : undefined)
+    // A duplicate response means this exact signed txID was already submitted.
+    if (code === 'DUP_TRANSACTION_ERROR') return
+    if (
+      result['result'] !== true ||
+      (typeof result['txid'] === 'string' &&
+        result['txid'].toLowerCase() !== signed.hash.slice(2).toLowerCase())
+    )
+      throw new BroadcastError(
+        'Tron rejected the subsidy transaction.',
+        typeof code === 'string' ? code : undefined,
+      )
+  }
+
+  async function status(
+    parameters: create.StatusOptions,
+  ): Promise<'pending' | 'reverted' | 'success'> {
+    assertChain(parameters.chain)
+    const client = Tron.createClient({ fetch: options.fetch, urls: parameters.chain.rpcUrls })
+    const receipt = await client.getTransactionReceipt({ hash: parameters.signed.hash })
+    if (!receipt) return 'pending'
+    const transaction = await client.getTransaction({ hash: parameters.signed.hash })
+    if (!transaction) return 'pending'
+    const call = transaction.raw_data.contract[0]?.parameter.value
+    const expectedData = AbiFunction.encodeData(transfer, [
+      Tron.toEvmAddress(parameters.recipient),
+      BigInt(parameters.signed.amount),
+    ]).slice(2)
+    if (
+      !call ||
+      call.owner_address.toLowerCase() !==
+        `41${Tron.toEvmAddress(parameters.signed.account).slice(2)}`.toLowerCase() ||
+      call.contract_address.toLowerCase() !==
+        `41${Tron.toEvmAddress(parameters.token).slice(2)}`.toLowerCase() ||
+      call.data.toLowerCase() !== expectedData.toLowerCase() ||
+      (call.call_value ?? 0) !== 0
+    )
+      return 'reverted'
+    if (
+      receipt.receipt.result !== 'SUCCESS' ||
+      receipt.result === 'FAILED' ||
+      transaction.ret.some(({ contractRet }) => contractRet !== 'SUCCESS')
+    )
+      return 'reverted'
+    const sender = Tron.toEvmAddress(parameters.signed.account).slice(2).toLowerCase()
+    const recipient = Tron.toEvmAddress(parameters.recipient).slice(2).toLowerCase()
+    const token = Tron.toEvmAddress(parameters.token).slice(2).toLowerCase()
+    const matched = receipt.log?.some(
+      (log) =>
+        log.address.toLowerCase() === token &&
+        log.topics.length === 3 &&
+        log.topics[0]?.toLowerCase() === transferTopic.toLowerCase() &&
+        log.topics[1]?.slice(24).toLowerCase() === sender &&
+        log.topics[2]?.slice(24).toLowerCase() === recipient &&
+        /^[0-9a-fA-F]{64}$/.test(log.data) &&
+        BigInt(`0x${log.data}`) === BigInt(parameters.signed.amount),
+    )
+    return matched ? 'success' : 'reverted'
+  }
+
+  async function post(
+    chain: Chain.Chain,
+    method: string,
+    body: object,
+  ): Promise<Record<string, unknown>> {
+    assertChain(chain)
+    for (const url of chain.rpcUrls) {
+      try {
+        const response = await options.fetch(`${url.replace(/\/$/, '')}/${method}`, {
+          body: JSON.stringify(body),
+          headers: { 'content-type': 'application/json' },
+          method: 'POST',
+          signal: AbortSignal.timeout(10_000),
+        })
+        if (!response.ok) continue
+        const result: unknown = await response.json()
+        if (isObject(result)) return result
+      } catch {
+        // Try the next configured Tron endpoint.
+      }
+    }
+    throw new UpstreamError('Tron RPC is unavailable.')
+  }
+
+  return {
+    account: options.account,
+    broadcast,
+    check,
+    policy: options.policy,
+    prepare,
+    sign,
+    status,
+  }
+}
+
+export declare namespace create {
+  /** Horcrux and native Tron RPC dependencies. */
+  type Options = {
+    /** Base58Check subsidy wallet address. */
+    account: string
+    /** Maximum native fee reserved per transaction, in SUN. */
+    feeLimitSun: number
+    /** Fetch implementation for Horcrux and chain RPC. */
+    fetch: typeof globalThis.fetch
+    /** Horcrux connection and authentication. */
+    horcrux: {
+      auth: { type: 'none' } | { clientId: string; clientSecret: string; type: 'cloudflare-access' }
+      url: string
+    }
+    /** Horcrux Tron wallet UUID. */
+    walletId: string
+    /** Operational maximum destination subsidy. */
+    policy: { maxAmount: string }
+  }
+
+  /** Creation-time inventory request. */
+  type CheckOptions = {
+    amount: bigint
+    chain: Chain.Chain
+    recipient: string
+    reservations: { nativeAmount: bigint; tokenAmount: bigint }
+    token: string
+  }
+
+  /** Unsigned transaction preparation request. */
+  type PrepareOptions = CheckOptions
+
+  /** Solidified receipt query and expected destination transfer. */
+  type StatusOptions = { chain: Chain.Chain; recipient: string; signed: Signed; token: string }
+}
+
+function assertChain(chain: Chain.Chain) {
+  if (chain.id !== 'tron:0x2b6653dc' || chain.kind !== 'tron' || chain.rpcUrls.length === 0)
+    throw new ConfigurationError('Unsupported Tron subsidy chain.')
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** The Tron subsidy wallet lacks token inventory or native TRX. */
+export class BalanceUnavailableError extends Error {
+  override name = 'Routes.TronTransferSubsidy.BalanceUnavailableError'
+}
+
+/** The Tron subsidy signer or chain configuration is invalid. */
+export class ConfigurationError extends Error {
+  override name = 'Routes.TronTransferSubsidy.ConfigurationError'
+}
+
+/** Horcrux could not provide a verified Tron signature. */
+export class SigningError extends Error {
+  override name = 'Routes.TronTransferSubsidy.SigningError'
+}
+
+/** Tron reported a rejected broadcast. */
+export class BroadcastError extends Error {
+  override name = 'Routes.TronTransferSubsidy.BroadcastError'
+
+  /** Native Tron broadcast rejection code, when supplied by the node. */
+  code: string | undefined
+
+  constructor(message: string, code?: string) {
+    super(message)
+    this.code = code
+  }
+}
+
+/** Returns whether the signed transaction has a deterministic validation failure. */
+export function isPermanentBroadcastError(cause: unknown): boolean {
+  return (
+    cause instanceof BroadcastError &&
+    ['SIGERROR', 'CONTRACT_VALIDATE_ERROR', 'TOO_BIG_TRANSACTION_ERROR'].includes(cause.code ?? '')
+  )
+}
+
+/** Tron RPC failed or returned incompatible transaction data. */
+export class UpstreamError extends Error {
+  override name = 'Routes.TronTransferSubsidy.UpstreamError'
+}

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

@@ -12,14 +12,17 @@ test('exports routes modules', () => {
       "Evidence",
       "Observability",
       "Provider",
+      "Quota",
       "Reconciliation",
       "Route",
+      "SolanaTransferSubsidy",
       "SourceObservation",
       "Subsidy",
       "Token",
       "Transfer",
       "TransferReconciliation",
       "TransferSubsidy",
+      "TronTransferSubsidy",
     ]
   `)
 })

package/src/internal/routes/index.ts

@@ -7,11 +7,14 @@ export * as DepositWebhook from './DepositWebhook.js'
 export * as Evidence from './Evidence.js'
 export * as Observability from './Observability.js'
 export * as Provider from './Provider.js'
+export * as Quota from './Quota.js'
 export * as Reconciliation from './Reconciliation.js'
 export * as Route from './Route.js'
+export * as SolanaTransferSubsidy from './SolanaTransferSubsidy.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'
 export * as TransferReconciliation from './TransferReconciliation.js'
 export * as TransferSubsidy from './TransferSubsidy.js'
+export * as TronTransferSubsidy from './TronTransferSubsidy.js'