> For the complete documentation index, see [llms.txt](https://docs.northstar.sonicsvm.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.northstar.sonicsvm.org/concepts/sessions.md).

# Sessions

A NorthStar **session** is a bounded, isolated execution context anchored to a Solana account. It runs as an Ephemeral Rollup — single-tenant, with its own slot cadence, fee economics, and account scope — for a configurable lifespan, then settles atomically back to L1.

## Anatomy

Every session has:

* **An owner** — the Solana keypair that opened it. Sessions are derived from `(portal, owner, gridId)`.
* **A grid id** — an integer chosen by the owner. Two sessions for the same owner must have different grid ids.
* **A TTL** — the maximum lifespan in slots. After expiry, accounts force-undelegate.
* **A fee cap** — the maximum lamports the session can spend on internal accounting. Once depleted, the session terminates.
* **A fee structure** — the schedule that governs per-instruction fees inside the session. Defaults to gasless on devnet; arbitrary in production.
* **A set of delegated accounts** — the on-chain state the session can write. Everything else is read-only (inherited from L1).

## Lifecycle

```mermaid
stateDiagram-v2
    state "Forced Undelegate" as ForcedUndelegate

    [*] --> Created: OpenSession\nmints session PDA + fee_vault
    Created --> Delegated: Delegate\nwritable on ER, locked on L1
    Delegated --> Active: ER processes txs at\nsession's slot cadence
    Active --> Closed: explicit close
    Active --> Expired: TTL elapsed
    Closed --> ForcedUndelegate
    Expired --> ForcedUndelegate
    ForcedUndelegate --> [*]: accounts settle back to L1
```

Five distinct states: Created → Delegated → Active → (Closed or Expired) → settled.

## What's local to the session vs. visible from L1

| Account state                                       | While session is active                                               | After session closes                          |
| --------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------- |
| **Delegated accounts** (pool, vault, agent keypair) | Writable on ER. **Locked** on L1 — no L1 transaction can modify them. | Settled atomically: all changes commit to L1. |
| **Non-delegated accounts** (mints, owner pubkey)    | Read-only on ER, inherited from L1                                    | Unaffected by session.                        |
| **Session metadata** (PDA, fee\_vault)              | Lives on L1 throughout                                                | Reaped on close (rent returned to owner).     |

## Constraints

* **One session per (owner, grid\_id)** — Portal won't open a duplicate.
* **Sessions don't compose** — a single transaction can't span two sessions; pick one.
* **Settle-back is all-or-nothing** — partial failures don't materialize.

## See also

* [Account delegation](https://github.com/mirrorworld-universe/northstar-docs/blob/main/concepts/delegation/README.md) — what makes an account writable on the ER.
* [Programmable economics](https://github.com/mirrorworld-universe/northstar-docs/blob/main/build/fees/README.md) — the FeeStructure parameter.
* [Settle-back guarantees](https://github.com/mirrorworld-universe/northstar-docs/blob/main/concepts/settle-back/README.md) — the atomicity model.
* [Real-time confirmation](https://github.com/mirrorworld-universe/northstar-docs/blob/main/architecture/real-time/README.md) — slot cadence inside a session.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.northstar.sonicsvm.org/concepts/sessions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.