> For the complete documentation index, see [llms.txt](https://docs.valantis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valantis.xyz/prime/developers/architecture.md). # Prime Architecture Valantis Prime follows an *Owner -> Account -> Connector (protocol) -> Action (function) -> Agent/SessionKey/Guardian (access)* chain of command. * The owner controls the Account, subject to Staking Discounts lifecycle restrictions if Prime Staking is enabled. * The Account CONTROLS external access to funds by agents and integrated protocols. * Connectors define WHAT external Actions can be done. * Agents, Guardians, and Session Keys control HOW those Actions are executed. ### Architecture ``` ┌─────────┐ │ Owner │ │ (You) │ └────┬────┘ │ ┌─────────▼─────────┐ │ Account │ │ │ │ Agents, Sessions │ │ Allowances, etc. │ └──────────┬────────┘ │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ HyperCore │ │ Lending │ │ Future │ │ Connector │ │ Connector │ │ Protocols │ └───────────┘ └───────────┘ └───────────┘ ``` This page is the technical model for Valantis Prime component boundaries, execution flow, and trust assumptions. For product rationale and positioning, start with [Valantis Prime Thesis](/prime/thesis.md). ## Owner You are the owner of your Account. As owner, you have: * Control over Account features, subject to delegated action permissions * Ability to add/remove agents and connectors (external access) * Control over all allowances and guardians (restrictions) * Power to start/end sessions (listed signing keys) * Authority to withdraw accessible Account balances; integrated protocol balances may be subject to withdrawal or lifecycle restrictions * Account recovery setup ## Account Your Account lets you configure: * **Who** can execute actions (Agents) * **What** protocols they can use (Connectors) * **How much** they can spend (Allowances) * **What rules** they must follow (Guardians) * **How long** access lasts (Sessions) Delegating a HyperCore action-admin role limits the owner’s control over that action. The owner cannot forcibly reclaim that role; see [Admin Role Transfers](/prime/developers/hypercore-connector.md#admin-role-transfers-protocol-integrated-hypercore-accounts). Prime staking-discount accounts also restrict the trader’s HyperCore access during shutdown, while EVM balances in the parent Account remain accessible. See the [Staking Discounts Risk Matrix](/prime/developers/staking-discounts-risk-matrix.md). ## Key Features #### **Protocol Integrations** (Connectors) Valantis Prime does not support arbitrary transactions natively, every Protocol/Action is integrated into the system carefully through Connectors. A Connector defines what actions can be called, and who can call them. * Implements custom business logic for a specific protocol * Restricts external calls to pre-approved contracts * Has its own access control and action types **Available Connectors:** * **HyperCore** - Bridge, trade, stake, transfer, vault operations, BLP deposits, API-wallet management, and builder-fee operations on HyperCore precompiles. (All HyperCore precompiles on Mainnet as of March 2026). * **STEX Lending** - Deposit/withdraw from STEX Multi Market Lending Optimizer integrated with AAVE and Morpho contracts (Felix, Hyperlend, HypurrFi, etc.). Each action in a Connector has defined permission controls: * What agents and session keys can call it * What restrictions those external callers have (Guardians) * Who can edit the permissions for an action (Admin/Owner) Connectors add an additional layer of protection through allowances. Since protocols are integrated directly into a user's account, allowances enforce that added connectors have limit access to funds. ``` HyperCore Connector: 1,000 USDC allowance STEX Lending: 500 HYPE allowance ``` Even if an agent or protocol is compromised, losses are limited to the allowance you've set. #### **Agents** Connectors define the actions, Agents automate them. Valantis Prime architecture is made to allow in-account Agent Automations without giving full control to external services. For example: * Allow a trading bot to place orders on HyperCore, but not withdraw funds * Allow a liquidation protection bot to add collateral, but not borrow or withdraw Each agent operates within strict boundaries you define, enforced by smart contract invariants. Agent can be further restricted by **Guardians**. Introducing a programmable safety-net on giving agents access to in-account automations. Guardians are smart contract callbacks that revert Agent actions under certain conditions. Each Connector can have one Guardian that implements: * `beforeExecute()` - Validates conditions before action * `afterExecute()` - Validates state after action **Example Use Cases:** 1. **Price Limits** ``` Guardian checks: Trade price must be within 2% of oracle If agent tries to trade at bad price → Guardian reverts ``` 2. **Health Factor Protection** ``` Guardian checks: Health factor must stay above 1.4 If action would drop health factor → Guardian reverts ``` 3. **Position Size Limits** ``` Guardian checks: Total position size < $10,000 If action exceeds limit → Guardian reverts ``` **Agents** have whitelisted actions, but **Guardians** apply criteria/restrictions to how/when Agents can call those actions. They are pre/post state checks that can limit an Agent's freedom over your funds. #### **Session Keys and Signing** Every non-critical action allows an owner to register a Session Key with a custom expiry. Session keys are whitelisted across the entire account + connectors, but each action can define how long that session key is valid for (can be set to 0 for no-session key allowed actions). This enables HyperCore actions that typically require a user signature to use session keys, overcoming the pre-defined nature of API wallets. This enables fine-tuned control of critical and non-critical operations across the account and it's integrations. For example, in yield-bearing DCA: * HyperEVM Lending + HyperCore whitelisting/allowances are set via owner signature * Order creation is done via a medium-expiry session key * Order cancellation is done via a long-expiry session key This enables smoother interactions without constant wallet pop-ups, and fine-tuned control by the owner to define their security comfort across all of Hyperliquid. Session keys can be revoked at any time by the owner. #### **Account Recovery** Valantis Prime allows the owner to set up state-of-the-art account recovery services natively in the account. Protect against lost private keys: * Pre-approve recovery wallet addresses * Set a recovery manager (trusted party or service) * If you lose access, recovery can transfer ownership after a time delay * You maintain control and can cancel at any time ### Security Model Valantis Prime account security is based on: 1. **Trusted Integrations** - Only call pre-approved external contracts and functions can be called 2. **Integration Allowances** - Token transfers to Integrated Protocols (Connectors) cannot exceed allowances. 3. **Session Time Limits** - Session keys expire (max 60 days) and can be revoked by owner at any time. 4. **Recovery Delays** - Ownership changes require multi-day time locks 5. **Guardian Validation** - Optional pre/post execution checks on agent actions #### What You Need to Trust * **Connector code** - Each Connector's logic (you should verify it's immutable and secure) * **Agents you authorize** - They operate within allowances but are trusted to act correctly * **Guardians you add** - They can block actions by agents, so must be correct implementations * **Recovery manager** - Can initiate recovery (but only to wallets you pre-approved) ### Next Steps * [Account Features](/prime/developers/account.md) - Learn about agents, sessions, allowances, and guardians * [HyperCore Connector](/prime/developers/hypercore-connector.md) - HyperCore-specific features