# Tokenised Vault Specifications

### Protocol Architecture & System Specification

### Abstract

This document provides the technical specification for the Tokenised Vault Protocol. The system is engineered as a non-custodial, yield-bearing primitive that enables users to tokenize underlying assets into a Yield Bearing Token (YBT).

The protocol architecture prioritizes solvency and risk segregation through a hub-and-spoke model. It implements an Asynchronous Redemption Model (logic aligned with ERC-7540) to manage liquidity duration, and a Temporal Yield Smoothing engine to mitigate MEV vectors. Liquidity is actively managed between on-contract capital and Adaptors connected to DeFi protocols.

### Smart Contract Modules

The protocol is composed of six primary upgradeable contracts, categorized by their functional domain within the stack.

#### Core Layer

The foundational contracts manage consensus, state, and tokenization.

<table data-header-hidden><thead><tr><th width="181.515625">Contract</th><th width="145.65625">Type</th><th>Functional Specification</th></tr></thead><tbody><tr><td><h4><strong>Contract</strong></h4></td><td><h4><strong>Type</strong></h4></td><td><h4><strong>Functional Specification</strong></h4></td></tr><tr><td>LSTokenVault</td><td>Core</td><td>The primary liquidity engine. It manages the On-Contract Capital / Adaptor allocation, calculates the exchange rate Index, and enforces yield vesting schedules.</td></tr><tr><td>LSToken</td><td>Token</td><td>A standard ERC20 implementation representing an ownership share on the Vault's assets. Features ERC20Permit for gasless approval signatures.</td></tr></tbody></table>

#### Settlement Layer

The operational contracts governing the egress of capital and liability management.

<table data-header-hidden><thead><tr><th width="177.390625">Contract</th><th width="153.58984375">Type</th><th>Functional Specification</th></tr></thead><tbody><tr><td><h4>Contract</h4></td><td><h4>Type</h4></td><td><h4>Functional Specification</h4></td></tr><tr><td>UnstakeManager</td><td>Logic</td><td>The settlement controller. It orchestrates the lifecycle of redemption requests (Queue -> Process -> Claim) and manages the cooldown parameters.</td></tr><tr><td>TokenSilo</td><td>Storage</td><td>An isolated settlement buffer. Funds moved here are strictly segregated from the Vault's risk, reserved solely for users with processed claims.</td></tr></tbody></table>

#### Security & Configuration Layer

The administrative contracts enforcing access control and emergency invariants.

<table data-header-hidden><thead><tr><th width="181.109375"></th><th width="149.859375"></th><th></th></tr></thead><tbody><tr><td><h4>Contract</h4></td><td><h4>Type</h4></td><td><h4>Functional Specification</h4></td></tr><tr><td>VaultManager</td><td>Admin</td><td>A stateless logic adapter for administrative configuration. It separates parameter mutability (fees, limits) from the core accounting logic.</td></tr><tr><td>EmergencyController</td><td>Security</td><td>A global access control module implementing a multi-tiered emergency response system, including the time-locked Recovery Mode.</td></tr></tbody></table>

### Core Primitives & Invariants

#### 1. Index-Based Yield Streaming

To neutralize flash-loan arbitrage and Just-In-Time (JIT) liquidity attacks, the protocol rejects atomic yield updates.

* Mechanism: Yield is injected via addYield(), creating a divergence between the lastIndex (current exchange rate) and the targetIndex (future rate).
* Invariant: The system linearly interpolates the exchange rate over a yieldVestingDuration.
* Outcome: This enforces a Time-Weighted Average Price logic for the YBT, rendering instantaneous manipulation economically non-viable.

#### 2. Active Liquidity Management

The Vault operates as a capital router, managing solvency through dynamic allocation.

* On-Contract Capital: A defined floatPercent of Total Assets is retained in the Vault to service immediate liquidity needs and fast-track small redemptions.
* Adaptors: Capital is deployed and allowed to interact with whitelisted protocols (e.g., Lending Markets) termed Adaptors. These are purely passthrough addresses to interface with specific protocols; they do not hold rights beyond the adaptor’s scope.

### Operational Workflows

#### 1. Deposit (Atomic Minting)

The entry flow is atomic, ensuring immediate exposure to the YBT yield.

1. Deposit: User transfers Underlying Assets to the LSTokenVault.
2. Minting: The Vault calculates the exchange rate based on the future targetIndex (to prevent front-running pending yield).
3. Allocation: Logic checks the floatPercent. On-Contract Capital is kept in the contract and remaining assets are deployed to the allowed Adaptors

#### 2. Redemption (Asynchronous Settlement)

To align with ERC-7540 logic and guarantee deterministic solvency, withdrawals follow a three-phase lifecycle.

1. Request (Liability Creation):

* User calls requestUnstake().
* YBT is burned immediately.
* A liability is crystallized in Underlying Asset terms and placed in the Queue.

2. Processing (Liquidity Fetch):

* The MANAGER\_ROLE executes processUnstakeQueue().
* The system aggregates pending liabilities and fetches required liquidity from the Vault On-Contract Capital.
* If On-Contract Capittal is insufficient, liquidity is recalled from Adaptors.
* Funds are moved to the TokenSilo.

3. Claim (Final Settlement):

* Funds in the TokenSilo enter a Sterile State, immune to Vault yield or slashing.
* After the cooldownPeriod elapses, the user executes a claim to retrieve their assets.

#### 3. Accelerated Exit

Users with processed claims in the TokenSilo may bypass the remaining cooldown.

* Logic: The user accepts a penalty fee (configurable. Currently set as 0).
* Execution: The UnstakeManager releases the user's principal minus the fee immediately.
* Fee Routing: Penalties are routed to the protocol treasury.

### Security Architecture

The EmergencyController enforces a defense-in-depth strategy, categorizing threats into three response tiers.

#### Tier 1: Operational Pause

* Scope: Granular suspension of specific functions (e.g., DEPOSITS\_PAUSED).
* Trigger: EMERGENCY\_ROLE.
* Use Case: Minor UI bugs or non-critical operational anomalies.

#### Tier 2: Circuit Breaker

* Scope: Global system freeze (FULL\_PAUSE).
* Trigger: EMERGENCY\_ROLE.
* Mechanism: Instantly halts all value movement and initiates a 24-hour timelock for Recovery Mode.
* Use Case: Suspected critical vulnerability or active exploit attempt.

#### Tier 3: Recovery Mode

* Scope: Protocol-level override.
* Trigger: EMERGENCY\_ROLE (post-timelock).
* Capabilities: Allows the ADMIN\_ROLE to execute forced migrations, rescue stranded assets, or patch logic without consensus checks.
* Invariant: Recovery Mode cannot be entered atomically; the mandatory delay provides a governance visibility window.