Arete documentation

Protocol API and authoring reference

Use this page to locate protocol interfaces after following the authoring or integration guide. Exact installed types and the generated README describe the release your application actually calls.

Authoring package

@usearete/protocol exports defineProtocol, ix, and builtins for protocol definitions; wirePreparedOperation, PrepareInputV1, and ProtocolContextV1 for handlers; and validators and types for public artifacts. @usearete/protocol/testing supplies runHandler and replay contexts.

Definition fields include programs, stacks, params, resources, roles, reads, machines, steps, metadata, reactions, events, and stack. Use the package’s TypeScript declarations for each nested schema and the package reference. Do not copy identity hashes from a sample instead of importing installed modules.

builtins(...) returns typed modules for the builtin programs, and ix checks their instructions like an installed program’s. Each builtin has one name: system, splToken, associatedToken, computeBudget and memo. Other names are errors that name the builtin: spl-ata and splAta are associatedToken, spl-token is splToken, system-program is system, spl-memo is memo and compute-budget is computeBudget.

const { associatedToken } = builtins("associatedToken");
ix(associatedToken, "createIdempotent", { accounts: { fundingAddress: "wallet" /* … */ } });

SPL Token’s owner and authority accounts are signers, so pass a key the step signs with, such as wallet or an ephemeral key. Templates cannot use a multisig token authority: its members would sign as remaining accounts, and remaining accounts never sign.

npx arete-protocol check [protocol.ts]
npx arete-protocol build [protocol.ts] --out .arete/protocol

Brackets indicate optional arguments, not literal shell syntax. --server-release selects server release derivation when needed for comparing release identities.

check runs local checks for syntax and names. With a secret key in ARETE_API_KEY, it also runs Arete’s own upload checks (expression types, and templates against their pinned program specs) without uploading anything. It prints each rejection’s spec path, message and code. Pass --remote to require the server check, or --offline to skip it. a4 protocol deploy --dry-run runs the same server check with your a4 login, and so does the MCP tool protocol_check. Normal development uses a4 dev up; production uses a4 protocol deploy.

TypeScript protocol client

createProtocolClient(definition, options) creates a standalone client. createSession({ protocols: { alias: definition } }, options) includes it in an application session.

Surface	Purpose
`steps.<name>.prepare(input, options?)`	Prepare a typed step or return a typed rejection
`actions({ wallet, instance?, cursor?, limit? })`	Wallet actions and related instances
`allowedSteps({ instance, wallet })`	Step availability for one instance
`instances.list(filter?)`, `instances.get(id, options?)`	Canonical instance reads
`instances.forWallet(wallet, { relation? })`	Every instance a wallet relates to, across pages of `actions`
`instances.use(id, options?)`	Reactive instance handle with optional live row
`participants.get({ instance, wallet })`	Canonical participant read
`submit(intent, signedTransactions)`	Submit exact wallet-signed transactions
`intents.get(executionId)`	Read execution outcome
`events(instanceId, options)`	Resumable instance event stream
`metadata.instance(id)`, `metadata.participant(input)`	Metadata handles and wallet proof messages
`squads.proposer()`, `status(multisig)`	The Squads proposer and whether it is an Initiate-only member
`getReceipt(signature)`, `getReceiptKeys()`	Receipt and verification keys
`stacks`, `programs`	Included definitions, or connected dependencies inside a session
`close()`	Release the client’s owned resources

The account’s Squads multisigs are set up on the dashboard or with a4 squads; code that creates a multisig or adds the proposer uses the Squads v4 program SDK’s Arete setup helpers. See Squads.

Secret-key clients expose client-callable steps; publishable-key clients are typed for public steps. Runtime access and authority checks still apply. Amounts use ProtocolInteger decimal strings. Prepare returns the discriminated ProtocolPrepareResult: check ok before reading intent and transactions.

React hooks

Hook	Purpose
`useProtocolInstance(client, id, options?)`	Canonical instance, optional live row, loading, error, refresh
`useWalletActions(client, input, options?)`	Wallet action discovery
`useAllowedSteps(client, input, options?)`	Availability for one instance and wallet
`useProtocolParticipant(client, input, options?)`	Participant state
`useProtocolEvents(client, id, options)`	Event subscription with unmount cleanup

React integration explains stable client ownership and event-driven refresh.

Rust and Python

Install verified targets with a4 install protocol <package> --rust or --python. Generated clients expose the same concepts with language-specific names and typed step arguments. Read their generated README for construction, imports, steps, rejection types, and event payloads.

Wallet action discovery uses actions in each language. A wallet’s instances across every page are instances_for_wallet(wallet, relation) in Rust (Option<&str>) and instances_for_wallet(wallet, relation=...) in Python. Receipt helpers use verify_receipt and verify_receipt_on_chain in Rust and Python. Python’s repository implementation is available for development; check its publication status before selecting it for distribution.

CLI and MCP

Protocol CLI commands cover init, deploy, actions, search, show, and listing requests. Dev commands cover environments, wallets, steps, streaming, replay, and debugging. Protocol MCP tools cover discovery, actions, prepare, submit, intent tracking, and receipts, with an optional local signer.