SessionFi

SessionFi is an intent‑based DeFi session protocol that lets users define outcomes instead of micro‑managing every transaction. A “session” is a container for swaps and routing actions governed by clear, on‑chain rules. The user signs intents like “swap token A to token B with a minimum output by a deadline,” and the SessionFi system executes within that envelope. This design makes swaps safer, less error‑prone, and much easier to compose across chains.

At the core, SessionFi unifies four systems into a single workflow:

Uniswap v4 Hooks on EVM, which enforce session rules at swap time. Yellow Network custody (state channels) to manage session funds efficiently. LI.FI routing to discover cross‑chain routes and quotes. Sui settlement for high‑performance finality and auditability. These aren’t just stitched together—they’re coordinated through a unified TypeScript client that exposes a clean API for session creation, deposits, intent execution, and optional cross‑chain routing.

The Session Model A session is created on‑chain in the SessionFi Hook. This session records the owner, a nonce, and a state hash. The session acts like a bounded environment: swaps inside it must respect intent parameters and available balances. If a swap exceeds the allowed amount or violates session constraints, the hook will reject it.

This is an important shift from normal DeFi usage. Instead of submitting isolated transactions, the user opens a session, funds it, and then executes multiple actions under shared rules. This supports complex flows such as “swap in stages,” “route across chains,” or “settle later once output is acceptable.”

Intent Execution Intents are signed messages that include tokenIn, tokenOut, amountIn, minAmountOut, and deadline. The unified client signs these intents and passes them to the hook for validation. The hook’s beforeSwap logic checks session validity and available allowance; afterSwap updates the session’s state hash and nonce.

That state hash matters because it becomes the anchor for downstream settlement. It provides a cryptographic record of the session’s evolution, which can later be mirrored on Sui or used for dispute resolution.

Cross‑Chain Routing When cross‑chain routing is needed, the unified client calls LI.FI to fetch routes and quotes. LI.FI returns structured route options with estimated output, gas cost, and route steps. The SessionFi client can select the best route and execute it while keeping session boundaries intact. This keeps the high‑level intent consistent even across multiple chains.

Settlement on EVM and Sui SessionFi supports settlement on EVM using the hook contract, but also targets Sui for high‑performance settlement. The Sui Move module records session state, enforces expiration, and emits settlement events before releasing funds. This gives SessionFi a path to scalable finality and multi‑chain accounting.

The Yellow Network component adds an important layer: state channels allow session custody to be managed off‑chain with on‑chain guarantees. This gives SessionFi an efficient custody pattern and a dispute‑resistant settlement pathway.

The Developer Experience For developers, the most direct entry point is the unified TypeScript client in src/unified/. It offers a single surface area for creating sessions, depositing tokens, executing swaps, and requesting cross‑chain quotes. This abstraction is significant: instead of integrating four SDKs, developers integrate SessionFi once.

The React app (IntegratedApp) is connected to the deployed Sepolia contracts and serves as a functional reference implementation. There’s also a mock UI (AMMApp) that can be used for demo‑only flows. The codebase includes a demo script, full contract code, and integration tests.

Why It Matters SessionFi’s architecture is meaningful because it separates execution from finality. Uniswap v4 Hooks enforce session rules at swap time, while Sui settlement and Yellow custody provide efficient finality and channel‑based custody. This makes SessionFi a strong candidate for real‑world DeFi workflows that need:

Fewer user approvals and reduced friction. Safe batching of actions within a session boundary. Cross‑chain execution without breaking intent integrity. Clear, auditable settlement records. SessionFi isn’t just a swap wrapper—it’s a session framework that turns DeFi actions into a programmable, intent‑driven lifecycle. It creates a new primitive for building user experiences where outcomes, not transactions, are the first‑class interface.

Whitepaper‑Style Technical Write‑Up (Formal / Structured) Title: SessionFi Protocol — Intent‑Based DeFi Sessions with Hook Enforcement, Cross‑Chain Routing, and Multi‑Chain Settlement

Abstract SessionFi is a multi‑chain protocol for intent‑based decentralized finance. It enables users to create time‑bounded sessions, deposit assets, and execute intent‑constrained swaps within those sessions. Enforcement occurs through Uniswap v4 hooks on EVM; routing is provided by LI.FI; custody can be managed via Yellow Network state channels; final settlement can occur on either EVM or Sui. A unified TypeScript client abstracts the complexity, allowing developers to integrate SessionFi with minimal surface area.

1. Problem Statement Traditional DeFi interactions are transaction‑centric. Users must manually approve tokens, execute swaps, and manage slippage across chains. This leads to fragmented workflows, error‑prone user experiences, and limited composability. Existing cross‑chain solutions can route swaps but do not enforce a consistent intent boundary across the lifecycle of multiple actions.

2. Design Goals SessionFi is designed around four goals:

Intent primacy: The user specifies outcomes, not transactions. Session safety: Swaps only occur within explicit allowances and deadlines. Multi‑chain flexibility: Routing and settlement are decoupled. Developer simplicity: A single client orchestrates all integrations. 3. System Architecture SessionFi integrates four key components:

Uniswap v4 Hooks: Enforce session rules at swap time. Yellow Network Custody: Optional state‑channel custody for efficient session management. LI.FI Router: Cross‑chain routing and quotes. Sui Settlement: High‑performance finality and audit events. A unified TypeScript client coordinates these systems and exposes a single API surface for creation, deposit, execution, and settlement.

1. Session Lifecycle 4.1 Session Creation A session is created via the SessionFi Hook contract, which stores an owner address, nonce, and state hash. The session is marked active and acts as a bounded execution container.

4.2 Deposits and Balances Assets are deposited into the session and recorded as available balances. The hook maintains these balances and ensures no swap exceeds the available amount.

4.3 Intent Definition An intent is a signed message containing:

tokenIn tokenOut amountIn minAmountOut deadline Intents are validated by the hook and used to constrain swaps.

4.4 Swap Execution (EVM) The hook’s beforeSwap enforces session validity and allowance. The afterSwap updates the session’s nonce and state hash. Each swap is thus cryptographically linked to the session state.

4.5 Cross‑Chain Routing When cross‑chain execution is required, the unified client requests routes from LI.FI, which returns optimal routing steps and estimates. The chosen route is executed while the session’s intent constraints remain enforced.

4.6 Settlement Settlement may occur on EVM through the hook, or on Sui using a Move contract. The Sui settlement flow verifies session validity, updates session state, emits settlement events, and releases funds.

1. Security Model The protocol’s security is grounded in:

On‑chain hook enforcement of session constraints. Signature‑based intent authorization. Cryptographic state hashes for session evolution. Optional Yellow Network state channel custody for dispute‑resistant settlement. Sui’s Move module, which verifies expiry and settlement state before releasing funds. 6. Developer Interface SessionFi exposes a unified TypeScript client that integrates hook sessions, LI.FI routing, Yellow custody, and Sui settlement. This reduces developer overhead and allows new applications to leverage intent‑based flows without integrating each dependency individually.

1. Current Deployment Status

Yellow Network custodian contract deployed on Sepolia. SessionFi Hook deployed on Sepolia. LI.FI routing integrated. Sui settlement module implemented, deployment pending. Unified client implemented and exported via src/unified/. 8. Future Work Planned milestones include Sui testnet deployment, enhanced documentation, audit readiness, and a production‑grade mainnet deployment. Additional work includes improving session orchestration UX and expanding intent capabilities.

Conclusion SessionFi introduces a new DeFi primitive: session‑bounded intent execution. By combining Uniswap v4 hook enforcement, Yellow Network custody, LI.FI routing, and Sui settlement, SessionFi creates a composable, multi‑chain workflow where outcomes are first‑class. This design simplifies developer integration, reduces user friction, and opens a path to scalable, intent‑native DeFi.

SessionFi was built as a multi‑chain, intent‑first DeFi system, so the biggest challenge wasn’t a single contract or frontend—it was coordinating how different layers behave as one coherent protocol. The architecture had to solve four things at once:

How to control swaps with rules (sessions) How to hold funds safely during those sessions How to route across chains without losing the intent How to settle the final outcome cleanly Instead of solving those separately, SessionFi ties them together under a single “session” abstraction and then builds each layer around that. Here’s how that construction actually happened, step‑by‑step.

1. The Core Primitive: Sessions The first thing we built was the session primitive, because everything else depends on it.

A session is essentially a stateful container that has:

an owner (the wallet that created it), a nonce (so every action is ordered and unique), a state hash (so the session’s history is cryptographically trackable), and balances/allowances (so swaps can’t exceed what the session is meant to control). This is implemented in the SessionFiHook contract. It’s built as a Uniswap v4 Hook because hooks can intercept swaps and decide whether to allow or reject them. That gives SessionFi a native enforcement layer—swaps literally cannot happen unless the session constraints are satisfied.

The key insight: if you want intent‑based swaps, the enforcement must happen at swap time, inside the liquidity engine itself. That’s why the hook is the “core.”

1. Uniswap v4 Hook: Enforcing Sessions at Swap Time Once the session structure was defined, we wired it into the hook lifecycle:

beforeSwap checks if the session is active, if the sender owns it, and if the swap amount is within the session’s allowance. afterSwap increments the session nonce and updates the session state hash. By doing this, every swap becomes a verified intent‑compliant action, and the session’s state evolves in a way that can be audited later or mirrored for settlement.

This is the fundamental enforcement engine.

1. Yellow Network Custody: Efficient Session Funding With session rules in place, we needed a way to hold assets efficiently during those sessions. If all assets stayed fully on‑chain, it would work—but it would be expensive and not scalable for high‑frequency actions.

That’s why the Yellow Network custodian contract was integrated. It provides a state channel model:

Users deposit into a channel. Off‑chain updates happen as state changes (more efficient). On‑chain settlement only happens at the end or in disputes. SessionFi uses this to provide custody guarantees without forcing everything on‑chain every time. It’s the right tool for a session system because a session is inherently stateful and often short‑lived.

1. LI.FI Routing: Cross‑Chain Intents Without Losing Control Once same‑chain sessions worked, the next problem was cross‑chain execution.

If you want a user to say: “Swap token A on chain X to token B on chain Y,” you can’t hardcode routes—those change constantly.

So SessionFi integrates LI.FI, which is effectively a universal cross‑chain router. The key was not just to get a quote, but to do it without breaking the session abstraction.

That’s why the unified client does two things:

It asks LI.FI for routes. It attaches those routes into the session flow as session‑bounded execution, meaning the intent still governs what’s allowed, even across chains. This preserves the “intent first” model while still enabling real cross‑chain routing.

1. Sui Settlement: Finality Layer for Sessions The last piece is settlement. On EVM, you can settle in the hook itself, but the vision of SessionFi is that sessions can be finalized on a fast execution layer. That’s where Sui comes in.

A Move contract was created to mirror session finality on Sui:

It stores session data. It verifies expiration and validity. It emits settlement events. It releases the session’s locked funds. This is important because it introduces multi‑chain finality: you can run execution on EVM but still close out a session on Sui for speed and clean event‑based state tracking.

1. Unified Client: Gluing Everything Together Once those four pillars existed, the last big step was to build the unified TypeScript client. This is where the “how it’s made” really matters, because this client is what makes the system usable.

The client hides the orchestration complexity and provides a simple flow:

Create a session on the hook Deposit tokens Execute swaps or get cross‑chain quotes Settle the session That means developers don’t need to understand Uniswap hooks, LI.FI routing, Yellow state channels, and Sui Move at the same time. They just call one client.

This is the true product layer.

1. Frontend and Demo Integration The React app (IntegratedApp) wasn’t just a UI—it was a live integration test. It proved that:

Sessions could be created and used with real deployed contracts. LI.FI routes could be fetched in a real flow. Hook logic enforced sessions correctly in practice. The UI is therefore not a separate piece—it’s part of the engineering validation. It exists to demonstrate that the architecture isn’t theoretical.

1. Why This Build Matters SessionFi isn’t just “one more DeFi app.” It’s a new abstraction: a session becomes the unit of interaction, and intent becomes the unit of control.

This required a deliberate build sequence:

Define session constraints. Enforce them in hooks. Secure custody for efficiency. Add cross‑chain routing. Build a settlement layer. Wrap it all in a unified client. Every piece was built so the session model stays intact from start to finish.