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

# Circles

> On-chain programmable spaces, gated by NFT ownership

Circles are a programmable access layer built on Octra's on-chain execution environment. Each Xpectrum collection gets one Circle: a sealed, collection-wide space where holders interact using their NFT as the key.

## What a Circle is

A Circle is an isolated execution environment deployed on Octra. It runs AML/OCTB bytecode, holds its own on-chain state, and can call other on-chain contracts directly. Circles are not databases or off-chain servers. They are first-class on-chain programs.

On Xpectrum, each collection has one Circle deployed alongside it. It stores the collection's metadata and art on-chain. Those assets are public and readable by anyone, that is how the marketplace and any indexer render the collection. "Sealed" means write access: once frozen, the assets cannot be changed. NFT ownership gates a Circle's programmable interactions (the holder-only logic below), not the reading of its public assets.

<Note>
  Circles are live on Xpectrum. The current implementation is collection-wide: one Circle per collection, accessible to holders. We are actively refining the access-control paths for efficiency.
</Note>

## Current capabilities

| Feature                                | Status |
| -------------------------------------- | ------ |
| Collection-wide sealed space           | Live   |
| On-chain asset storage (metadata, art) | Live   |
| NFT-gated access                       | Live   |
| AML/OCTB bytecode execution            | Live   |
| On-chain contract calls from a Circle  | Live   |

## How access works

Access is verified at the contract level, not in a backend:

1. Ownership is checked against the Xcollection contract via the XNS-1 interface (`owner_of` / `is_approved_or_owner`)
2. If the caller holds a token from the collection, access is granted
3. The holder interacts with the Circle's on-chain state directly from their wallet

No session tokens, no server. Verification happens on every interaction.

## What creators can build with Circles

Circles expose programmable logic configured at deploy time:

* **Token-gated communities** - discussion, voting, or coordination spaces for holders
* **Holder rewards** - on-chain claim mechanics tied to NFT ownership
* **Collection governance** - holder votes recorded as on-chain state
* **Gated content** - content addressable on-chain, unlocked by ownership verification

## On-chain calls

A Circle can call other contracts on Octra via `call(address, "method", args)`:

* Read state from Xcollection (verify ownership, check token metadata)
* Read listing state from Xmarket
* Call any other XNS-1 compliant contract on the network

## Horizon

<Warning>
  The items below are exploratory. None are live and none have a confirmed timeline. They depend on Octra network capabilities that are still maturing.
</Warning>

The current implementation is collection-wide. Future directions under consideration:

* Richer Circle programmability, including per-token state where each NFT carries its own isolated logic
* Cross-collection interaction between Circles
* Integration with Octra's FHE layer for private Circle state

This page will be updated as these reach mainnet.