Arete

Build and run Solana protocols: compose programs into workflows with typed steps, permissions, and lifecycle; develop in persistent cloud mainnet forks; and connect applications and agents through generated clients.

Packages

Package	Language	Registry	Description
arete	Rust	crates.io	Umbrella crate re-exporting all components
arete-interpreter	Rust	crates.io	AST transformation runtime and VM
arete-macros	Rust	crates.io	Proc-macros for stream definitions
arete-server	Rust	crates.io	WebSocket server and projection handlers
arete-sdk	Rust	crates.io	Rust client SDK
a4-cli	Rust	crates.io	Project setup, catalog discovery, dependency management, SDK generation, and deployment
arete-idl	Rust	crates.io	IDL parsing and type system
arete-hash	Rust	crates.io	Typed artifact identity and canonical hashing protocol
arete-artifacts	Rust	crates.io	Versioned public artifact schemas and legacy normalization
@usearete/protocol	TypeScript	npm	Protocol authoring, contracts, handler ABI, and build tooling
@usearete/hash	TypeScript	npm	TypeScript implementation of the artifact identity protocol
@usearete/sdk	TypeScript	npm	Pure TypeScript SDK (framework-agnostic)
@usearete/react	TypeScript	npm	React SDK with hooks
@usearete/adapter-kit	TypeScript	npm	Wallet adapter for @solana/kit
@usearete/adapter-web3js	TypeScript	npm	Wallet adapter for @solana/web3.js
arete-sdk	Python	PyPI	Python client SDK (work in progress - not yet published)

Product model

A protocol composes Solana programs into typed steps with guards, authority, instance and participant lifecycle, metadata, and events. Applications install a protocol client; agents use the same workflow through MCP. Cloud dev environments provide a persistent mainnet fork for developing and exercising the protocol before an explicit production deployment.

Program SDKs provide account reads and instruction builders. Live views maintain application-shaped data, and stacks package those views with their programs. These capabilities support protocols and remain available independently.

See docs.arete.run for the complete product and SDK documentation.

Build a protocol

a4 protocol init my-protocol
cd my-protocol
npm install
a4 dev up

Requires the a4 CLI, Node.js 22.13+, and an Arete account with cloud dev-environment access. The CLI, dev UI, and wallet keys stay local; the protocol runs against a hosted mainnet fork. Use a4 dev step to exercise it. Private dev handlers can run without review; production handlers require review.

Start with Build your first protocol, or integrate an existing protocol. Program SDKs and live views remain available independently.

CLI setup and standalone capabilities

CLI

Install the prebuilt, signed a4 binary (no Rust toolchain or account needed):

curl -fsSL https://arete.run/install.sh | sh        # macOS / Linux
irm https://arete.run/install.ps1 | iex             # Windows PowerShell
npx @usearete/a4 install                            # if you prefer npm

Then, in your project:

a4 init -y          # arete.toml, AGENTS.md block, agent skills, MCP config
a4 doctor --json    # ready when the JSON status is "ok"
a4 explore catalog --query "token accounts" --json
a4 explore catalog program spl-token --json
a4 install program spl-token --ts

Update with a4 self update. Coding agents can do all of this from one prompt:

Read https://docs.arete.run/agent.md and follow it to set up Arete in your environment. Verify the setup, and simply explain what Arete is capable of.

See cli/README.md for the full command surface.

Explore on-chain through MCP

a4 init configures the local Arete MCP server. An agent can search the catalog and knowledge layer, inspect exact view schemas, connect to a deployed stack, subscribe to a bounded live view, and query its local cache while answering a question. MCP also exposes protocol action discovery, preparation, submission, and receipts, with an optional policy-bound local signer. Use generated SDKs in shipped application code.

Hosted knowledge and connections may require a4 auth signup or a4 auth login --key <key>.

Rust

cargo add arete

TypeScript (Core)

npm install @usearete/sdk

TypeScript / React

npm install @usearete/react @usearete/sdk zod

Generated React consumers use the React hooks, core SDK types, and generated Zod schemas. zustand is a normal dependency of @usearete/react; applications do not install it separately.

Hosted browser stacks can require authentication. Use the publishable-key name reported by the selected stack descriptor and pass it to the provider as auth={{ publishableKey }}. Read-only viewing does not require a wallet.

Python

Note: The Python SDK is a work in progress and has not yet been published to PyPI. Treat Python availability as descriptor-specific.

# Coming soon
pip install arete-sdk

Capabilities

Capability	Application surface
Program accounts	Generated program.accounts readers, pinned to an exact release
Generic Solana state	Shared chain reader for raw accounts, balances, mints, rent, and clock
Transaction construction	Generated raw builders, operations, transactions, and flows
Transaction execution	Local wallet signing with explicit inspect and submit phases
Live data	Generated point-in-time queries and WebSocket view subscriptions
Agent exploration	Catalog, knowledge, live connections, and bounded cached queries through MCP

The exact package descriptor reports which modes (read, build, or subscribe) and SDK targets are ready. Catalog knowledge alone does not imply that every delivery mode is available.

Artifact and runtime model

Arete keeps portable behavior separate from the infrastructure that serves it:

Concept	What it represents
ProgramSpec	Portable program identity: program ID, normalized public IDL, account and instruction definitions, PDAs, and compatibility hashes. It contains no endpoint or managed decoder binding.
LiveSpec	Entities, mappings, handlers, computed fields, resolvers, and views over exact ProgramSpecs.
StackManifest	A client-facing composition of ProgramSpecs and aliased LiveSpecs, including the exact selected views. It contains no deployment URL.
Program Release	A hosted, immutable binding from one ProgramSpec to managed decoder behavior. Changing decoder semantics creates a new release.
Deployment	A hosted runtime prepared for one exact StackManifest. Images, regions, replicas, and rollout state belong here rather than in portable artifacts.
Binding	An operational endpoint and authentication attachment for a live deployment, Program Read release, chain reader, or transaction relay. Bindings can change without changing portable artifact hashes.

The Rust DSL writes authoritative artifacts directly during compilation.

cargo build

# Typical outputs:
# .arete/<program>.program-spec.json
# .arete/<StackName>.live-spec.json
# .arete/<StackName>.stack-manifest.json

An IDL-only module generates ProgramSpecs, a zero-live StackManifest, and a program-only spec() with generated account readers:

use arete::prelude::*;

#[arete(idl = ["idl/my_program.json"])]
mod my_program {}

let spec = my_program::spec();

Local spec() generation derives release fingerprints automatically from each ProgramSpec and the generated decoder-engine contract. An OSS server does not select or publish a hosted Program Release.

Use the explicit artifacts for CLI workflows:

# Create a standalone ProgramSpec directly from an IDL.
a4 program build ./idl/my_program.json \
  --output ./.arete/my_program.program-spec.json

# Compose one or more LiveSpecs under stable aliases. Repeating
# --selected-view creates the exact ordered client allowlist.
a4 stack compose --name my-app \
  --live core=./.arete/Core.live-spec.json \
  --artifact-dir ./.arete \
  --selected-view core=Position/list \
  --output ./.arete/MyApp.stack-manifest.json

# Generate local source, or deploy the exact manifest.
a4 sdk create --manifest ./.arete/MyApp.stack-manifest.json --ts
a4 sdk create --manifest ./.arete/MyApp.stack-manifest.json --rust
a4 up ./.arete/MyApp.stack-manifest.json

# Install a hosted SDK pinned to a published Program Release and read binding.
a4 install program spl-token --ts

# After an owner-private upload reaches ready, install it by alias or stable ID.
a4 program push ./idl/my_program.json --program-id <PUBKEY> --alias my-program --wait
a4 install program my-program --ts
a4 install program upr_... --ts

# Discover by intent, then inspect the same pinned descriptor before installing.
a4 explore catalog --query "token accounts" --kind program --json
a4 explore catalog program spl-token --json

Owner-private install lookups use the credentials saved by a4 auth login and are intentionally absent from registry discovery. A managed catalog name wins an alias collision; the returned upr_... ID always identifies the owner's registration unambiguously.

A composed client keeps live queries, each program's Program Read transport, generic chain reads, and transaction submission independent. Do not infer one endpoint from another.

a4 sdk create writes local source only. Publishing generated packages to npm or crates.io is an explicit operator action. Likewise, deployment produces endpoint bindings, not a required DNS provider: operators hand those endpoints to their chosen DNS/CDN provider and manage records and certificates there.

Repository Structure

• arete/: Main umbrella crate
• interpreter/: AST transformation runtime and VM
• arete-macros/: Proc-macros for stream definitions
• arete-idl/: IDL parsing and type system
• rust/arete-server/: WebSocket server and projection handlers
• rust/arete-a4-sdk/: Rust client SDK
• cli/: CLI tool for SDK generation
• typescript/core/: Pure TypeScript SDK
• typescript/react/: React SDK with hooks
• typescript/adapters/: Wallet adapters for @solana/kit and @solana/web3.js
• python/arete-sdk/: Python client SDK
• stacks/: Stack implementations and local SDK generation config
• packages/: Additional packages
• examples/: Example projects

Releasing

This repo uses release-please for automated releases.

How it works

1. Make commits using conventional commit format:

   • feat: add new feature - triggers minor version bump
   • fix: resolve bug - triggers patch version bump
   • feat!: breaking change - triggers major version bump
   • chore:, docs:, refactor: - no version bump

2. Push to main - release-please automatically creates/updates a Release PR

3. Merge the Release PR - this:

   • Updates CHANGELOG.md in affected packages
   • Bumps versions in Cargo.toml, package.json, pyproject.toml
   • Creates a GitHub Release with a unified version tag
   • Triggers publish workflows to crates.io, npm, and PyPI

Configuration

File	Purpose
release-please-config.json	Package definitions and release settings
.release-please-manifest.json	Tracks current version of each package

The first Python release also requires a PyPI pending trusted publisher for project arete-sdk, owner/repository AreteA4/arete, workflow release-please.yml, and environment oss-pypi-publication. The release job uses GitHub OIDC and does not accept a long-lived PyPI token.

Synchronized Versions

All core packages (Rust, TypeScript, and Python) are kept at the same version number using the linked-versions plugin. When any package receives a version bump, all packages are updated to the highest version in the group. This ensures compatibility when using packages individually.

Note: arete-idl is currently versioned independently.

Tag format

Tags follow the pattern v{version} (e.g., v0.5.10). Since all packages are version-synchronized, a single tag represents all packages in the release.

Development

Prerequisites

• Rust: 1.70+ (install via rustup)
• Node.js: 16+ (for TypeScript SDK)
• Python: 3.9+ (for Python SDK)

Building from Source

# Clone the repository
git clone https://github.com/AreteA4/arete.git
cd arete

# Build all Rust packages
cargo build --workspace

# CLI from source (unreleased builds only; the supported install is the
# installer above, and a Cargo-built binary cannot `a4 self update`)
cargo install --path cli
# or the published crate: cargo install a4-cli

# Build TypeScript SDKs
cd typescript/core && npm install && npm run build
cd ../react && npm install && npm run build

# Install Python SDK in development mode
cd python/arete-sdk && pip install -e .

Running Tests

# Rust tests
cargo test --workspace

# Rust linting
cargo clippy --workspace -- -D warnings

# TypeScript tests
cd typescript/core && npm test
cd ../react && npm test

# Python tests
cd python/arete-sdk && pytest

Project Structure

arete/
├── arete/          # Rust umbrella crate
├── interpreter/         # AST transformation runtime and VM
├── arete-macros/   # Proc-macros for stream definitions
├── arete-idl/      # IDL parsing and type system
├── cli/                 # CLI tool (a4-cli)
├── rust/
│   ├── arete-sdk/      # Rust client SDK
│   └── arete-server/   # WebSocket server
├── typescript/
│   ├── core/            # Pure TypeScript SDK (@usearete/sdk)
│   ├── react/           # React SDK (@usearete/react)
│   └── adapters/        # Solana wallet adapters
├── python/arete-sdk/   # Python client SDK
├── stacks/              # Stack implementations and SDKs
├── packages/            # Additional packages
├── examples/            # Example projects
└── docs/                # Documentation (MDX)

Documentation

• Build your first protocol

• Protocol concepts

• Cloud dev environments

• Integrate a protocol

• Deploy and publish

• What is Arete?

• From Question to Application

• Programs, Views, and Stacks

• Program SDKs

• CLI Commands

• React SDK

Contributing

We welcome contributions! Here's how to get started:

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Make your changes
4. Run tests (cargo test --workspace)
5. Commit using conventional commits format
6. Open a pull request

Commit Message Format

We use conventional commits for automated releases:

Prefix	Purpose	Version Bump
feat:	New feature	Minor
fix:	Bug fix	Patch
feat!: or fix!:	Breaking change	Major
docs:	Documentation only	None
chore:	Maintenance	None
refactor:	Code refactoring	None

Code Style

• Rust: Follow rustfmt defaults, pass clippy with no warnings
• TypeScript: Follow ESLint configuration in typescript/
• Python: Follow PEP 8

License

This project uses a dual license approach:

• Rust infrastructure (arete, interpreter, arete-macros, server, cli): Apache-2.0
• Client SDKs (TypeScript, Python, Rust SDK): MIT