Universal Router

FanX Universal Router — Empowering Seamless Swap Experience

The FanX Universal Router is a unified gateway for CHZ and ERC-20 transactions, enabling composable and efficient trade flows across FanX 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 FanX 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 — Bytecode Commands Engine

Instead of relying solely on predefined function calls, the FanX 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.

---

Permit2 — 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.