> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inkwell.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Keys

> How Leviathan uses scoped, ephemeral session keys to enable delegated execution within policy bounds.

> **CONFIDENTIAL & PROPRIETARY © 2026 Inkwell Finance, Inc. All Rights Reserved.**
>
> This document is for informational purposes only and does not constitute legal, tax, or investment advice, nor an offer to sell or a solicitation to buy any security or other financial instrument. Any examples, structures, or flows described here are design intent only and may change.

## Overview

Session keys are a core mechanism in Leviathan that allows borrowers and automated agents to **execute operations without requiring full wallet authority**. They are scoped, time-bounded, and revocable — designed to give borrowers the flexibility to operate within their policy sandbox while maintaining the security guarantees that lenders depend on.

## The Problem Session Keys Solve

Without session keys, every borrower action would require either:

* **Full wallet signing** — giving the borrower unrestricted access to move capital (unacceptable for lenders)
* **Per-transaction lender approval** — requiring the lender to co-sign every trade, deposit, or withdrawal (unworkable at scale)

Session keys provide a middle path: **pre-authorized, limited-scope execution** that lets borrowers operate freely within defined bounds.

## How Session Keys Work

```mermaid theme={null}
graph TD
    A[Session Key Created] --> B[Scoped to Operations]
    B --> C[Time Bounded]
    C --> D[Nonce Tracked]
    D --> E[Borrower Executes Actions]
    E --> F{Within Scope?}
    F -->|Yes| G[Action Executed]
    F -->|No| H[Action Rejected]
```

### Creation

A session key is created with specific parameters:

* **Authorized operations** — which types of actions the key can perform (e.g., trading on specific venues, depositing to approved yield sources)
* **Expiration time** — a timestamp after which the key is no longer valid
* **Initial nonce** — the starting value for replay protection

Session keys are recorded on-chain as Solana accounts, making their scope and validity publicly verifiable.

### Execution

When a borrower (or their automated agent) wants to perform an action:

1. The action is signed with the session key
2. The `leviathan-core` program checks that:
   * The session key has not expired
   * The action falls within the key's authorized scope
   * The nonce is correct (preventing replay)
   * The action passes policy verification (`leviathan-verifier`)
3. If all checks pass, the action is executed
4. The nonce is incremented

### Expiration

Session keys have a hard expiration:

* After the expiration timestamp, the key is rejected regardless of other conditions
* There is no automatic renewal — a new session key must be explicitly created
* Expired session key accounts can be cleaned up to reclaim rent

## Security Properties

### Time-Bounded Validity

Every session key has a defined lifetime. This limits the window of exposure if a key is compromised — an attacker who obtains a session key can only use it until it expires, and only for the operations it was scoped to.

### Scope-Limited Authority

Session keys cannot do anything outside their defined scope:

* A key scoped to "trade on DEX A" cannot withdraw funds from DEX A
* A key scoped to "deposit into yield vault B" cannot interact with any other contract
* Scope is enforced at the program level — it cannot be bypassed by constructing creative transactions

### Nonce Tracking

Every action taken with a session key increments an on-chain nonce:

* Each action must include the expected nonce value
* If the nonce doesn't match, the action is rejected
* This prevents **replay attacks** where a previously valid signed action is resubmitted

Nonce tracking ensures that even if an attacker captures a signed transaction, they cannot re-execute it.

### Revocability

Session keys can be revoked before their natural expiration:

* The loan owner can revoke a session key at any time
* The protocol can revoke session keys if policy violations are detected
* Revocation is immediate — once revoked, the key is rejected on the next attempted use

## Use Cases

### Automated Trading

A borrower deploys capital to trade on approved decentralized exchanges:

* Session key scoped to trade execution on whitelisted DEXs
* Automated trading bot uses the session key to execute strategies
* The bot can trade freely within the approved venues but cannot withdraw capital

### Yield Deployment

A borrower deploys idle capital to approved yield sources:

* Session key scoped to deposit and withdrawal on specific yield vaults
* Capital can be moved between approved yield sources as conditions change
* The session key cannot redirect capital to non-approved destinations

### Keeper Operations

Protocol keepers use session keys with narrow scopes:

* Drawdown keepers have keys scoped to executing scheduled deployments
* Health check keepers have keys scoped to reading state and triggering alerts
* Each keeper type has only the minimum authority needed for its function

## Session Keys vs. Full Authority

| Property                | Session Key                   | Full Wallet             |
| ----------------------- | ----------------------------- | ----------------------- |
| Scope                   | Limited to defined operations | Unrestricted            |
| Duration                | Time-bounded                  | Permanent               |
| Replay protection       | Nonce-tracked                 | N/A                     |
| Revocable               | Yes, at any time              | Only by key rotation    |
| Suitable for automation | Yes — scoped and safe         | No — too much authority |

Session keys are the mechanism that makes **policy sandboxing practical**. Without them, the choice would be between giving borrowers too much power or requiring impractical manual oversight for every action.