Events, metadata, and backend integration

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

Use events to keep an application current and trigger your own backend work. Use canonical reads with your credentials to fetch the details needed by that work, rather than assuming an event contains the full instance.

Follow an instance

const subscription = client.events(instanceId, {
  onEvent(event) {
    console.log(event);
  },
  onError(error) {
    console.error(error);
  },
});
// When this view or worker is disposed:
subscription.close();

The client reconnects and resumes after the last event id. You can supply lastEventId when starting a subscription. Treat a stream event as a reason to refresh the affected state; a displayed live row is not an execution result.

React users can use useProtocolEvents or the instance hooks.

Receive named emissions through webhooks

A protocol’s emit reactions publish named events. Configure an endpoint subscription for the required event names with the protocol owner. Webhooks are signed POST deliveries; process only verified requests.

import { verifyWebhook } from "@usearete/sdk";

const rawBody = await request.text();
const verified = verifyWebhook(webhookSecret, rawBody, request.headers);

Verify the raw bytes before parsing or reserializing them. The verifier checks signature and timestamp tolerance (five minutes by default). Keep the endpoint secret on your server. Use the stable delivery verified.id to deduplicate retries. Payloads carry identifiers and state; read further details with your own authenticated client.

Generated protocol modules also export a typed webhook verifier. See their README.md for the exact generated name. Deliveries can retry: make downstream work idempotent. Your backend owns notifications, email, and external business logic.

To run protocol steps for users when an event arrives, for example refunding everyone who opted in when a raise fails, use automations.webhookHandler from @usearete/automations. It verifies, records and deduplicates deliveries for you. See Automate steps for users.

Update declared metadata

const metadata = client.metadata.instance(instanceId);
const current = await metadata.get();

Use metadata.update(patch) only for fields your credentials may write. A participant-writer update also takes a wallet proof; construct the exact message using the handle’s proofMessage, sign it, and pass walletProof in the update options. Inspect generated schemas for writable fields and types. Metadata is off-chain application data, separate from transaction settlement.

Onboard Squads when required

For protocols with multisig administration, the multisig in the deployment config must be attached to your account and active. Set it up on the dashboard (app.arete.run/dashboard/squads), which works with any browser wallet, or in the Squads app (add the proposer as a member with the Initiate permission only). From code, use the Arete setup helpers of the Squads v4 program SDK (a4 install program squads-v4); the member’s wallet signs. A deployment refused with protocol-squads-setup-required carries the multisig’s dashboard link in details.setupUrl. Per deployment, client.squads.proposer() and status(multisig) report the proposer and whether it is an Initiate-only member.

Arete can propose the declared admin action; it does not vote or execute the multisig proposal. Handle missing-proposer events as an onboarding requirement, not as evidence that the admin step completed.