> For the complete documentation index, see [llms.txt](https://kayen-finance.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kayen-finance.gitbook.io/docs/protocol-mechanics/kayenfi-v3/universal-router.md).

# Universal Router

## Empowering Seamless Swap Experience

Kayen Finance's **Universal Router** is a unified gateway for **CHZ** and ERC-20 transactions, enabling composable and efficient trade flows across KayenFi V2 and V3 protocols. This stateless, immutable contract allows developers and users to consolidate a wide range of operations into a single execution path without requiring multiple separate transactions.

## Core Capabilities

* **Composable Multi-Route Swaps**: \
  Seamlessly combine and interleave swap paths across KayenFi V2 and V3 in a single request.
* **Partial Execution**: \
  Optionally continue execution when certain steps fail, allowing partial fills without canceling the entire transaction.
* **CHZ ↔ wCHZ Wrapping**: \
  Automatically wrap or unwrap CHZ as part of swap flows.
* **Permit2 Compatibility**: \
  Integrates with Permit2 to streamline approval processes, minimizing or eliminating separate token approval steps.
* **Advanced Position Management**: \
  Supports V3 liquidity operations, including permits, modifications, and pool initialization.
* **Complex Logic Support**: \
  Allows execution of multi-step, conditional transaction flows with balance checks and sub-plan execution.

## How It Works

Instead of relying solely on predefined function calls, KayenFi's **Universal Router** uses a **command interpreter** structure:

* The main entry point, `execute(bytes commands, bytes[] inputs[, uint256 deadline])`, processes a sequence of byte-sized instructions paired with corresponding byte-array parameters.
* Each command is encoded as a single byte (`bytes1`), which contains:
  * A flag bit to indicate whether the command’s failure should halt execution or allow continuation.
  * A reserved bit for potential future use.
  * A command identifier (6 bits) mapping to specific actions such as swaps, wrapping/unwrapping, position changes, or Permit2 logic.

This architecture effectively operates like a “mini virtual machine” within a single transaction, giving users and developers the flexibility to design complex workflows that are executed atomically.

## Modernizing Token Approval Mechanics

**Permit2** is a unified token approval system that combines two advanced mechanisms into one contract design:

* **SignatureTransfer**: \
  Enables single-use, signature-based token transfers without setting a standing allowance. The authorization is valid only for the specific transaction.
* **AllowanceTransfer**: \
  Allows users to set a capped and time-limited allowance, enabling contracts to spend tokens only within those predefined limits.

## Integration and User Experience

To use Permit2, a one-time approval of the Permit2 contract is required. In most cases, granting the maximum possible allowance (`type(uint256).max`) is recommended for smoother ongoing interactions.

Permit2 improves security by avoiding repeated approvals, reducing the risk of unlimited token allowances, and enabling more granular, time-bound permissions, while also improving the user experience by removing redundant approval steps.