How Arete Works

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /using-stacks/how-it-works.md.

Arete keeps two things apart. On one side are portable definitions: what a program’s interface is, and what a view contains. On the other are the hosted services that deliver them. Your application gets exact, generated interfaces either way, and never has to care how the infrastructure behind them is laid out.

This page walks through each part in order. You don’t need all of it to get started. If your agent is doing the building, skim the path below and come back when you want to know what a particular step involves.

The complete path

Intent
  ↓
Catalog and knowledge
  ↓
Exact program or stack descriptor
  ↓
arete.toml + arete.lock
  ↓
Generated SDK
  ↓
Application session
  ├── Program Read
  ├── Generic chain reads
  ├── Live view queries and subscriptions
  └── Transaction inspection and submission

You can look inside every step on that path. Agents use the catalog to find things, exact descriptors to learn what is truly available, and generated code as the API your application calls.

Discovery: find capabilities from intent

The catalog lists programs and stacks along with their concepts, categories, verified SDK targets, and the modes each one supports:

• read for typed program accounts and general chain state;
• build for instructions, transactions, and flows (the package has instruction builders; it says nothing about use in protocols); and
• subscribe for hosted current-state and live views.

A search result is not an SDK schema. Once the agent has a candidate, a4 explore opens its pinned descriptor. That descriptor is the source of truth for the specific version your application can install.

Installation: turn discovery into a project dependency

a4 install records what you asked for, in readable form, in arete.toml. It records exactly what that resolved to in arete.lock. Then it generates code for your language, plus a record of where that code came from, for the whole set of dependencies.

A project can declare:

• standalone Program SDKs;
• stacks containing live views and their programs;
• more than one SDK target; and
• local or workspace-authored artifacts where that makes sense.

Each dependency is resolved for its own SDK targets: its targets, else the project’s [sdk] targets. Not every package publishes every target. When a new dependency would need one its catalog entry doesn’t list, a4 install stops before resolving anything and names the fix: install it with --ts, or set its targets. The catalog entry describes the package’s current release, so this check applies when you install that release; a requested version it doesn’t satisfy is left to the resolver. a4 protocol init sets [sdk] targets = ["typescript"], since a protocol project is TypeScript.

Generation is all-or-nothing. The outputs and the lockfile are committed together, and only after the complete set of dependencies validates.

Program Read: exact decoded accounts

Program Read fetches and decodes accounts for one exact published program release. The generated client already knows the schema and the release identity. Reach for it when you have an address and want the current state that program owns.

It works independently of live views. A standalone Program SDK can be read-ready with no deployed stack anywhere.

Chain gateway: generic state and transactions

Some things aren’t tied to any one program’s account schema. The Solana gateway covers those:

• general account, balance, mint, rent, and clock reads;
• transaction blockhash, fee, and simulation support; and
• submission and confirmation for locally signed transactions.

Read access and transaction access are granted separately. The wallet compiles and signs on your machine, and Arete never receives the private key.

Hosted packages carry explicit gateway descriptors. Clients don’t work out the gateway address from a stack’s WebSocket URL.

Live views: maintained application state

Live views turn a stream of account and instruction updates into entities your application can use directly. A view can offer keyed state, a collection, or a bounded window that is filtered and sorted.

Clients can:

• fetch a point-in-time result over HTTP;
• subscribe to updates over WebSocket;
• apply keys, filters, partitions, and limits on the server side; and
• bring application state back in line after a confirmed transaction.

View subscriptions distinguish between kinds of update. A row can be added or changed, it can drop out of one query while still existing, or it can be deleted everywhere. The generated SDK handles those cases for you, so use it instead of flattening every update into an upsert/delete pair.

MCP: the exploratory client

The local Arete MCP server gives an agent access to catalog search and live-view operations. It can connect to a deployed stack, keep a bounded cache for active subscriptions, and query that cache while it answers your question.

MCP is ideal for exploring and debugging. Once a capability belongs in a product, install its exact package and use the generated SDK.

Sessions: application composition

A session brings several stacks and programs together and lets them share authentication, chain reads, wallet access, and transaction transports. Each generated package still keeps its own exact identities and connection details.

const session = await createSession({
  stacks: { markets: MARKETS_STACK },
  programs: { token: SPL_TOKEN_PROGRAM },
});

session.stacks.markets.views;
session.programs.token.accounts;
session.chain;

Custom views

When no existing view answers your application’s question, you can define a new one using the advanced Rust authoring path.

Compiling produces definitions. Deploying attaches hosted capabilities to them. After deployment, query the result through MCP, refine it, and install the finished stack into your application.

Public contracts versus implementation

Applications should depend on:

• catalog capability metadata;
• exact descriptors and artifact identities;
• generated SDK types;
• documented query and transaction semantics; and
• explicit authentication scopes.

They should not depend on internal service names, how deployments are grouped, storage layout, compiler processes, or endpoint conventions they have inferred. Those are implementation details, not part of the public contract.

Continue

• Programs, views, and stacks
• Explore with MCP
• Program SDKs
• Connect to live views