# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.defx.com/docs/resources/tokenised-vault-specifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.