a4-server

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /a4-server/overview.md.

Self-hosting is optional

If you use Arete’s hosted catalog and stacks, you can skip this whole section. It is for teams who want to run live views or typed reads on servers they control.

a4-server is a Rust crate that runs generated Arete behavior in your own infrastructure. A live server can connect to Yellowstone gRPC, process Solana data through projections, and stream results to clients. The same builder can instead run a program-only spec() and expose typed account reads without starting a live projection runtime.

This is the open-source stack server for projections and typed reads. It does not run hosted protocol deployments or cloud dev environments. For those, follow protocol development and deployment.

Portable Artifacts vs Runtime Configuration

The Rust DSL keeps these concepts separate:

• A ProgramSpec identifies portable public program behavior. It has no endpoint or managed decoder selection.
• A LiveSpec defines entities, mappings, and views over exact ProgramSpecs.
• A StackManifest composes aliased LiveSpecs and selected views for clients.
• A hosted Program Release immutably binds a ProgramSpec to managed decoder behavior.
• A deployment runs one exact composition; a binding attaches an endpoint and authentication policy to a live, program, chain, or transaction capability.

Self-hosted a4-server remains code-first:

Server::builder().spec(my_stack::spec())

The generated spec() supplies parsers, account readers, and automatic local release fingerprints derived from ProgramSpecs and the decoder-engine contract. It does not require a hosted registry, public release manifest, or decoder selection.

Independent Runtime Surfaces

Do not treat one server URL as part of artifact identity. The builder enables runtime surfaces independently:

Surface	Builder configuration	Client transport
Live views	.websocket() and the generated live runtime	Per-LiveSpec WebSocket transport
Program reads	.program_reads()	Per-program HTTP transport and release/binding
Chain reads	.chain_reads()	Generic Solana chain-read transport
Transactions	.transactions_config(...)	Transaction inspect/send transport

.http() is a convenience that enables health, Program Read, chain-read, and stack-query routes together; transaction routes remain disabled until explicitly configured. A composed client can use multiple live aliases and multiple program bindings while choosing completely separate chain and transaction transports.

Prerequisites

To run a stack with a4-server, you need:

Requirement	Description
Yellowstone gRPC Endpoint	Required for a live runtime. A URL to a Solana node running the Yellowstone Geyser plugin.
X-Token	Usually required when the selected Yellowstone provider authenticates live streams.
Rust 1.75+	Required to build the server binary.
A compiled definition	Your crate with the #[arete(...)] macro, which generates a live or program-only spec() function.

Yellowstone Access Required

You must have access to a Yellowstone gRPC endpoint when enabling live projections. Program-only reads do not require Yellowstone. Live options include:

• Running your own Solana validator with the Yellowstone Geyser plugin
• Using a provider like Triton, Helius, or similar that offers Yellowstone gRPC

Environment Variables

a4-server reads configuration from environment variables:

Variable	Required	Description
YELLOWSTONE_ENDPOINT	For live runtime	Your Yellowstone gRPC endpoint URL
YELLOWSTONE_X_TOKEN	Provider-specific	Authentication token for the endpoint

When to Use a4-server

Use a4-server when:

• Developing and testing stacks locally
• Running a single stack in your own infrastructure
• You need full control over the server deployment
• You already have Yellowstone gRPC access
• You need a program-only typed read service without live views

Consider Arete Cloud when:

• You need multi-stack orchestration
• You want managed Yellowstone infrastructure
• You need built-in authentication and API keys
• You prefer zero-config deployment