> ## Documentation Index
> Fetch the complete documentation index at: https://shield.fi/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-hop swaps

> Build and settle current two-hop and three-hop routes.

`swap_multi_hop` executes two or three connected pools in one transaction. The route, amounts, directions, limits, nonce, and block-height deadline are public. Funding and delivered token records remain private.

## Request

The request contains endpoint token IDs, native base-unit input and minimum output, a confidential recipient, three `SwapHop` slots, hop count, nonce, block-height deadline, and confidential caller.

Each hop contains pool key, direction, and a Q128.128 square-root-price limit. `hop_count` must be two or three. For two hops, supply a valid deterministic placeholder in `hop2`; the finalizer does not execute it.

## Continuity

For each hop, derive input and output from the pool's canonical token order and `zero_for_one` flag. The contract requires:

1. Hop 0 input equals request input.
2. Hop 0 output equals hop 1 input.
3. For three hops, hop 1 output equals hop 2 input.
4. The final executed hop output equals request output.

Symbols are not identifiers. Compare concrete token fields.

## Execution bound

Each active hop walks at most three initialized ticks, followed by a partial fill bounded by the nearer next tick or price limit. Hop 0 can leave unspent original input. Hop 1 must consume all hop 0 output. In a three-hop route, hop 2 must consume all hop 1 output. A nonzero later-hop remainder rejects the whole route because the claim ABI cannot return an intermediate token. The final aggregate output must also meet `amount_out_min`.

Intermediate output feeds the next hop inside the finalizer. The current `SwapOutput` stores only final output and remaining original input. It does not create public per-hop refund slots.

## Settlement

After acceptance, read `swap_outputs[swap_id]` and call `claim_swap_output`. The function returns one final-output record and one original-input refund record. It validates the same confidential-address relation and signer freezelist proof used by single-hop settlement.

Use `swap_mh_from_wrapped` when route input begins as an underlying wrapped-asset record. Use a matching router claim function when final output or original-input refund must be unwrapped.

## Quote checklist

* Route has exactly two or three active hops.
* Every pool and token ID comes from the selected deployment.
* Route topology revision is current.
* Each pool state snapshot is current and enabled.
* Per-hop Q128.128 limits point in the correct direction.
* Quote reproduces three crossing iterations plus bounded partial behavior.
* Quote proves that every later hop consumes its full intermediate input.
* Final minimum uses output-token base units.
* Deadline is an Aleo block height.
* Original input record is sufficient.
* Factor and confidential-address recovery material are durable.