/**
 * Canonical request types for the `POST /compose/route` convenience endpoint.
 * Amounts accept `bigint | string` for authoring convenience; the JSON wire
 * format is always a decimal string, which the SDK serialises for you.
 *
 * `/compose/route` trades authoring power for brevity. Instead of a full flow
 * document it takes a single from/to token pair; the server plans a route for
 * that pair, builds the flow with a `directDeposit` input on the caller's
 * behalf, and runs it through the same compile pipeline as `POST /compose`.
 * The route is the shortest admissible chain of routing-catalog edges up to an
 * operator-set hop ceiling, and may begin with an aggregator swap when the
 * catalog alone cannot connect the pair. Terminal hops route through
 * `lifi.zap`, or `lifi.zapAsync` when the pair is reachable only
 * asynchronously and the request set `allowAsyncRoutes`. The route itself is
 * not disclosed: node ids are `hop0`, `hop1`, … with the terminal always
 * `zap`, so `outputs['zap.amountOut']` is the terminal output at every route
 * length and intermediate outputs carry `role: 'consumed'`. Its response body
 * is byte-identical to that of `POST /compose` — the enveloped
 * `ComposeCompileSuccessData` on HTTP 200 and `ComposeCompilePartialData` on
 * HTTP 206 — so this file declares only the request shape and reuses
 * `ComposeCompileResult` from `./compile.js` for the result.
 *
 * These are the single source of truth for the request shape, hand-authored
 * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
 * derived from the validating schema: that schema is the Zod one in
 * `@lifi/api-schemas` (`src/routes/composeRoute.ts`), a package that depends on
 * this one, so importing its inferred types here would invert the dependency —
 * and the public SDK ships this package as its only peer dependency, never the
 * server's schema package. The two definitions are held in lockstep by a
 * compile-time conformance assertion
 * (`api-schemas/src/routes/composeRoute.typecheck.ts`), which fails the build
 * if either side drifts.
 */

import type { SimulationPolicy } from './compile.js';
import type { ForwardTo } from './flowSchema.js';

/**
 * Spend an exact amount of `fromToken`.
 *
 * `amount` is in the token's smallest unit. Accepts `bigint | string`; the wire
 * format is a non-negative decimal string.
 */
export interface RouteAmountExact {
  readonly type: 'EXACT';
  readonly amount: bigint | string;
}

/**
 * Spend the signer's entire `fromToken` balance, whatever it is at execution
 * time.
 *
 * The on-chain amount is resolved by a deposit-all materialiser, so it is not
 * known when the route is compiled. `simAmount` is the stand-in the server
 * quotes and simulates against — make it a realistic estimate of the balance,
 * because it determines the quote and the derived preconditions, not the amount
 * actually moved. Accepts `bigint | string`; the wire format is a non-negative
 * decimal string.
 *
 * Not supported when `fromToken` is the chain's native sentinel: a gas coin
 * arrives via `msg.value`, so there is no on-chain balance to sweep, and the
 * server rejects the combination with a `validation_error`. Use
 * {@link RouteAmountExact} for native inputs.
 *
 * On a route that begins with an aggregator swap the swap's input amount is
 * pinned to the quoted amount derived from `simAmount`: a runtime balance below
 * that pinned amount reverts, and a balance above it leaves the remainder as
 * `unspentIn`, which may be most of the input and which `sweepTo` receives.
 * Under `EXACT` the deposit and the pinned quote are the same number, so the
 * `unspentIn` output is zero and omitted; any pre-existing dust of the sold
 * token in the proxy is moved to `sweepTo` by the whole-balance sweep
 * independently of that output.
 */
export interface RouteAmountAll {
  readonly type: 'ALL';
  readonly simAmount: bigint | string;
}

/**
 * How much of `fromToken` a route spends. Two variants, discriminated by
 * `type`.
 */
export type RouteAmount = RouteAmountExact | RouteAmountAll;

/** Request body for `POST /compose/route`. */
export interface ComposeRouteRequest {
  /** EVM chain id. Both tokens must live on this chain — routes are same-chain. */
  readonly chainId: number;
  /**
   * Token to spend. Use the chain's native sentinel address for the gas coin
   * (the zero address on EVM-native chains).
   */
  readonly fromToken: string;
  /** Token to receive. */
  readonly toToken: string;
  /** How much of `fromToken` to spend — an exact amount or the whole balance. */
  readonly amount: RouteAmount;
  /** Address that funds the route and, by default, owns its output. */
  readonly signer: string;
  /**
   * Slippage tolerance in basis points. Range 0–10000. Defaults to `100` (1%)
   * server-side when omitted. It is an end-to-end tolerance: the floor is the
   * simulated final output of the whole route, so a multi-hop route is not
   * bounded hop by hop. When the route begins with an aggregator swap the same
   * value is also the swap's own tolerance, which nests inside the end-to-end
   * floor rather than compounding with it.
   */
  readonly slippageBps?: number;
  /**
   * Reject the route when its quoted price impact exceeds this many basis
   * points. Range 0–10000. Omitted ⇒ the server's default of 500 bps applies;
   * `0` disables the check.
   */
  readonly maxPriceImpactBps?: number;
  /** Opaque referrer tag forwarded to the underlying quote provider. */
  readonly referrer?: string;
  /**
   * Owner of every asset the route leaves behind; defaults to `signer` on a
   * route with no aggregator swap. Routes whose protocol mints to a named
   * receiver (surfaced as `recipient: 'required'` by `GET /compose/zap-packs`)
   * and asynchronous routes bind this address at mint time rather than
   * transferring afterwards; otherwise the proxy's whole balance of each
   * asset the route leaves is transferred here.
   *
   * **Required when the route includes an aggregator swap.** Such a route can
   * leave an asset the caller did not plan for — the swap's unspent input —
   * and this address receives it alongside the terminal output, so it must be
   * named explicitly; omitting it fails with `validation_error`.
   *
   * Accepts an address or `{ $ref: 'context.sender' }` (which counts as
   * explicit); `{ $ref: 'context.executionAddress' }` is rejected.
   */
  readonly sweepTo?: ForwardTo;
  /**
   * `'strict'` (the default) fails the request when simulation detects a
   * revert; `'allow-revert'` returns a partial result with revert diagnostics
   * instead.
   */
  readonly simulationPolicy?: SimulationPolicy;
  /**
   * Also simulate the final user-facing transaction after the structured
   * simulation succeeds. Reverts honour `simulationPolicy`. Defaults to `false`.
   */
  readonly simulateUserProgram?: boolean;
  /**
   * Filter the returned `approvals` against current on-chain allowances,
   * omitting approvals that are already sufficient. Defaults to `false`.
   */
  readonly checkOnChainAllowances?: boolean;
  /**
   * Accept a route whose output is delivered only after the initiating
   * transaction settles (`delivery.when: 'future'` on the terminal output).
   * Such a route obliges you to track settlement rather than treat the
   * transaction as completing the job, and carries no slippage floor, so it is
   * opt-in. Defaults to `false` server-side, which leaves a pair reachable
   * only asynchronously rejected with `no_route_error` and guarantees every
   * terminal output is `delivery.when: 'now'`.
   *
   * It widens reach, it is not a preference: a synchronous route wins at any
   * length, so a pair with both a one-hop asynchronous edge and a longer
   * synchronous route is served synchronously. Opting in never costs you a
   * synchronous route.
   */
  readonly allowAsyncRoutes?: boolean;
}
