Documentation Hub
OneYield Protocol Documentation
Clean, structured documentation for the OneYield demo stack — from product problem and architecture to protocol model, agent operations, real on-chain wiring, and reliability principles.
Written in plain language so investors, users, and technical teams can all understand what the protocol does, how it works, and where value and risk are managed.
Introduction · Section 1
The Problem OneYield Solves
Overview: OneYield is a OneChain-native protocol that lets users keep principal discipline while unlocking daily spending utility from yield-oriented flows.
Problem Context
Most DeFi products force a tradeoff: either lock funds for yield or withdraw everything to spend. That breaks continuity for real users who need both growth and liquidity in the same cycle.
Core Promise: Deposit once, track principal separately, and spend from approved spendable balances without repeatedly dismantling your entire position.
Product Direction: OneYield is built as a practical financial workflow, not a speculative dashboard. Every major state transition is intended to be observable and explainable to users.
Why It Matters: Users get a smoother everyday experience while preserving long-term capital behavior through explicit reserve and settlement rules.
Architecture · Section 2
Layered System Design
Overview: OneYield is intentionally split into layers so economic truth, business orchestration, and user experience each stay cleanly separated.
Problem Context
Without layer boundaries, financial apps become fragile: UI guesses final state, backend over-assumes chain outcomes, and debugging critical money flows becomes risky.
Frontend Layer (Next.js): Handles wallet UX, navigation, dashboard narratives, and spend actions while always reflecting lifecycle states like pending, confirmed, or failed.
Backend Layer (NestJS): Orchestrates auth, queues, indexing, adapter calls, and reconciliation. It coordinates complexity but does not replace on-chain finality.
On-Chain Layer (Move): Maintains reserve and settlement guarantees as the economic source of truth for deposits, credits, and spend-related transitions.
Realtime + Data Layer: MongoDB and event streams preserve history, explainability, and resilient retries for async operations across the protocol.
Protocols · Section 3
What Protocol Building Blocks Power OneYield
Overview: OneYield uses protocol-inspired building blocks for principal protection, yield routing, and spend settlement, adapted to OneChain-native design.
Problem Context
A protocol cannot claim reliability if integrations are ad-hoc. Structured adapters and bounded integrations are required to keep upgrades safe and operations auditable.
Vault + SpendBuffer Primitives: Vault-oriented reserve accounting protects principal pathways, while SpendBuffer-oriented logic handles spendable credits and settlement order.
Lane-Based Routing: Lane architecture introduces explicit capital paths so allocation logic is understandable, testable, and incrementally upgradeable.
Adapter Pattern: Integrations are accessed through interfaces, allowing safe migration from stubs to live protocol interactions without rewriting core business modules.
Transaction-Backed Accounting: Yield and spend claims should map to confirmed on-chain events or deterministic reconciliation logic, not purely simulated counters.
Agents · Section 4
How the Agent System Works
Overview: Agents in OneYield are orchestration assistants, not uncontrolled actors. They propose or execute bounded actions inside policy and contract constraints.
Problem Context
AI without guardrails is risky in finance. Strategy assistance must improve responsiveness while remaining subordinate to deterministic protocol rules.
Decision Scope: Agents evaluate lane conditions, available signals, and policy limits to produce allocation or operation suggestions.
Execution Boundaries: No agent path should bypass adapter checks, backend validation, or contract-level guarantees. Final economic state is always chain-anchored.
Auditability: Each meaningful agent-driven action must be observable through logs, events, transaction references, and resulting balance state changes.
User Trust Model: Users should see what changed, why it changed, and what impact it had — making automation transparent rather than opaque.
Experience · Section 5
End-to-End User Flow
Overview: The user journey is intentionally linear: authenticate, deposit, configure, monitor, spend, and withdraw — with transparent status at every step.
Problem Context
Many DeFi apps hide complexity behind optimistic UI. OneYield instead surfaces operational truth so users understand lifecycle progression and source-of-funds behavior.
Connect + Sign: Wallet signature establishes identity and unlocks protected app routes tied to a verified session.
Deposit + Confirm: Deposit states move from submitted to confirmed, with backend reconciliation ensuring app state matches chain finality.
Monitor + Interpret: Dashboard and activity feeds present principal, yield, and spendability in a way that aligns with protocol constraints.
Spend + Settle: Spend actions follow source priority and settlement rules, producing traceable metadata for each transaction outcome.
Withdraw + Close: Exit flows resolve position state according to vault rules and preserve an auditable history of final transitions.
Execution · Section 6
Real On-Chain Wiring
Overview: OneYield is moving from simulation-style assumptions to transaction-backed operations for yield harvest, crediting, and settlement lifecycles.
Problem Context
If displayed balances are not traceable to chain events, trust erodes quickly. Economic credibility requires deterministic links between UI state and confirmed on-chain outcomes.
Critical Invariant: Principal reserve must remain protected; yield simulation should never consume user principal to fabricate performance.
Operational Readiness: Services need robust read/write paths: reserve queries, LP state checks, and safe transaction methods for harvest and credit routines.
Idempotent Cycles: Periodic jobs must tolerate retries and interruptions without double-crediting or irreversible inconsistencies.
Traceability: Every critical write should emit actionable logs and references so engineering teams and users can inspect outcomes confidently.
Reliability · Section 7
Safety and Reliability Principles
Overview: Safety is enforced as a system-wide discipline: contract invariants, adapter boundaries, queue correctness, and user-facing truthfulness all work together.
Problem Context
Financial products fail when reliability is treated as a patch. OneYield treats reliability as architecture, not a post-release checklist.
Deterministic Spend Policy: Source order and fallback behavior are explicit so every settlement can be explained and audited.
Idempotent Infrastructure: Retry-safe jobs prevent duplicate credits and allow controlled recovery from partial workflow failures.
Chain-Reconciled Truth: Off-chain projections improve UX, but chain-confirmed state resolves final correctness for economic interpretation.
Operational Hardening: Typed transaction builders, guarded admin actions, and observability-first logging are baseline requirements for production maturity.