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

# Core Concepts

### The pipeline: intent to execution

Every action in the Vishwa system follows the same path:

```
You / Agent  --->  Gateway (Vishwa API)  --->  Control layer (TEE)  --->  Execution
plain-English      receives the               verifies the request       signs & settles
intent             unsigned request           against your constraints   only on a passing proof
```

1. **You or your agent states intent** in plain English ("buy France 10 yes contracts in this market").
2. **The gateway** (`api.vishwalab.com`) receives the action as an unsigned request - a proposal. The agent cannot sign or send a transaction on its own.
3. **The control layer** runs the request through verification inside a Trusted Execution Environment (TEE), against a constraint policy sealed by the owner.
4. **Execution** happens only on a passing proof. The control layer signs and submits; a failing request is denied before anything irreversible occurs.

### The three checks

Every request is verified on three axes before it signs:

* **Authorization.** Is this agent allowed to take this action, on this venue? Operations and venues are allow-listed per agent.
* **Solvency and limits.** Is the request within the owner's per-trade, daily, and monthly caps, and covered by actual balances?
* **Execution fidelity.** Is the fill price within the owner's slippage tolerance against the live market? The control layer pulls oracle and venue prices independently, so it can reject a bad fill that a transaction-shape check would miss.

### Constraint policies

A constraint policy is the owner's rulebook, sealed inside the TEE. It is invisible to both the agent and the wallet - the agent only ever learns "allowed" or "denied."

```json
{
  "authorized_agents": [{
    "id": "agent:vishwa-cli",
    "allowed_operations": ["buy_contracts", "sell_contracts"],
    "per_operation_limits": {
      "buy_contracts": {
        "per_tx_usd": 20,
        "daily_usd": 100,
        "monthly_usd": 1000,
        "approved_venues": ["polymarket"],
        "max_slippage": 0.02
      }
    }
  }],
  "global_constraints": {
    "daily_limit_usd": 100,
    "rate_limiting": { "max_operations_per_minute": 5 }
  }
}
```

| Field                                      | What it enforces                                                           |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| `allowed_operations`                       | Which actions the agent may take (e.g. buy/sell only - never transfer out) |
| `approved_venues`                          | The allow-list of execution venues                                         |
| `per_tx_usd` / `daily_usd` / `monthly_usd` | Spend caps per trade, per day, per month                                   |
| `max_slippage`                             | How far a fill may drift from the live market price                        |
| `rate_limiting`                            | Maximum operations per minute - blocks runaway loops                       |

### The operating roles: Ciara, Naro, Veta

In vault deployments, the control-layer model is expressed as three named roles:

* **Ciara - the curator.** Defines approved strategies, allocation frameworks, and risk parameters: the rules the vault may operate under.
* **Naro - the AI coordinator.** Monitors positions, liquidity, market conditions, and opportunities; proposes or triggers allocation, rebalancing, and de-risking within Ciara's framework.
* **Veta - the verification layer.** Independently checks every capital movement against the predefined constraints before execution. Naro cannot move capital on its own.

In short: Ciara defines the rules, Naro operates within them, Veta enforces them. The same separation - proposer, policy, verifier - underlies the Vishwa CLI, where you are the curator of your own constraint policy.

### Key properties

* **The agent never holds keys.** It proposes; it cannot execute.
* **Constraints are sealed in hardware.** Neither the agent nor the wallet can read or alter the policy.
* **Verification is pre-execution.** A failing request is denied before signing - there is no approve-after-the-fact loop.
* **Market data is independent.** The control layer sources its own prices rather than trusting the agent's view of the market.
* **Every movement is auditable.** Executed actions return transaction signatures on-chain.