Program SDKs

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

A Program SDK is the basic thing you install with Arete. It takes one exact published release of a Solana program and turns it into generated code for reading accounts, working out addresses, building instructions, preparing operations, and executing transactions.

You can install a Program SDK on its own. No live stack is required.

If your app uses a stack that covers this program, its Program SDK is already included. A stack includes the Program SDK for each program its views read from: the same program package release a standalone install gives you, under the stack’s programs, so you don’t need to install the program again. Run a4 explore stack <ref> --summary to see which Program SDKs a stack includes.

Find a program

Search by what you want to do:

a4 explore catalog --query "token accounts" --kind program --json
a4 explore catalog --query "multisig proposals" --mode build --json

When you want exact filters, list the vocabulary first:

a4 explore catalog --vocabulary
a4 explore catalog --concept <concept> --kind program --json

Then open the exact descriptor for the program you picked:

a4 explore catalog program <slug> --json

The descriptor is the program’s spec sheet. It reports the program identity, its accounts, instructions, and types, whether the hosted Program Read service is available, which SDK targets are verified, and the exact install command. Don’t assume a language is supported because another program supports it, or because an old example used it.

The descriptor’s semantic version tells you about compatibility for this published Arete integration. Its content hashes identify the exact artifacts behind it. See Program Versioning for the automatic bump rules and generated release notes.

Install it

Initialize the project once, then add the program as a dependency:

a4 init -y
a4 install program <slug> --ts

Use --rust or --python when the descriptor lists that target. A saved install:

1. writes what you asked for to arete.toml;
2. resolves the complete, exact set of dependencies;
3. generates the code for your language; and
4. commits the generated output and arete.lock together.

The CLI prints where the code was generated and how to import it. Go by that output, not a path copied from another project.

The generated surface

Every Program SDK is organized into the same namespaces. What you find inside each one comes from the program’s own package:

Namespace	Purpose
programId	Exact executable address
schemas	Generated account and instruction schemas
pdas	Typed PDA derivation
addresses	Known or derived addresses
accounts	Typed, release-pinned account readers
queries / read	Additional connected reads when defined
raw	Exact IDL-shaped instruction builders
instructions	Prepared single-instruction operations
transactions	Prepared transaction operations
flows	Multi-step or multi-transaction workflows
constants, defaults, math	Generated domain helpers when available

To learn the exact member names and arguments, inspect the generated types, or ask your agent to summarize them for you.

Choose the right level

A Program SDK lets you work at several levels, from “just read this account” up to “run this whole flow”. Pick the highest level that does the job.

Read an account

Use program.accounts.<account>.fetch(address) or fetchMany(addresses) when you need a decoded account that the installed program owns.

Program Read →

Read generic Solana state

Use session.chain for lamports, rent, clock, raw accounts, mint state, token accounts, or any other data that doesn’t have a generated program-account reader.

Chain reads →

Prepare an application operation

When a generated operation or flow expresses your task, prefer it. Operations accept values in the form your app already has them, derive the routine accounts, perform whatever reads they need, and return a portable prepared result that includes signer and error metadata.

const prepared = await session.programs.myProgram.transactions.deposit.prepare({
  owner,
  amount: { ui: "10.5" },
});

Preparation may read current state, and that state can move. A prepared quote is not a reservation. If price, nonce, eligibility, or account state could go stale, prepare again close to execution.

Build a raw instruction

Use raw.<instruction>.build(...) when you deliberately want the normalized IDL wire shape, or when you are composing instructions yourself:

const instruction = session.programs.myProgram.raw.deposit.build({
  owner,
  amount: 10_500_000n,
});

Raw builders run offline and have no side effects. They fail on unknown parameters and on missing required values, but they don’t do any application-level preparation for you.

Inspect and execute

Inspecting is read-only. Executing requires a wallet, signs locally, and uses either the transaction capability named in the generated descriptor or a direct or custom transport you chose explicitly.

const inspection = await session.stacks.app.inspectOperation(prepared);
const receipt = await session.execute(prepared);

Inspection lives on the connected client that owns the operation. Execution is also available through the composed session.

Reading, building, preparing, inspecting, signing, and submitting are separate actions. When you ask an agent to “show me the transaction,” you have not authorized it to sign or submit.

Transaction lifecycle →

Add views only when the application needs them

Program SDKs cover reading from a program and sending it transactions. Install a stack when your application also needs maintained, app-shaped views or stack-level operations. The stack includes the Program SDK for each program its views read from, so a program the stack covers needs no separate install. If you already installed the program on its own, keeping it is fine: when both come from the same program package release, they are one program at runtime.

Programs, views, and stacks →