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.

Contract	Type	Functional Specification
LSTokenVault	Core	The primary liquidity engine. It manages the On-Contract Capital / Adaptor allocation, calculates the exchange rate Index, and enforces yield vesting schedules.
LSToken	Token	A standard ERC20 implementation representing an ownership share on the Vault's assets. Features ERC20Permit for gasless approval signatures.

Settlement Layer

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

Contract	Type	Functional Specification
UnstakeManager	Logic	The settlement controller. It orchestrates the lifecycle of redemption requests (Queue -> Process -> Claim) and manages the cooldown parameters.
TokenSilo	Storage	An isolated settlement buffer. Funds moved here are strictly segregated from the Vault's risk, reserved solely for users with processed claims.

Security & Configuration Layer

The administrative contracts enforcing access control and emergency invariants.

Contract	Type	Functional Specification
VaultManager	Admin	A stateless logic adapter for administrative configuration. It separates parameter mutability (fees, limits) from the core accounting logic.
EmergencyController	Security	A global access control module implementing a multi-tiered emergency response system, including the time-locked Recovery Mode.

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.

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

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