Skip to main content
This guide applies only to Solana devnet Preview 1. Owner setup creates explicit bounded authority; the agent proposes and signs executions within it. On-chain checks remain authoritative even if the API, agent, or browser is compromised.

Mandate lifecycle

An authority or engine epoch change is a validity condition, not a promise that every old mandate view is rewritten to revoked. Inspect independent owner epochs and grant/delegate state too. An old paused/active record can be unexecutable. Rent returns to the recorded rent payer. Owner epoch records persist so closing/recreating accounts cannot restore stale authority. For an API-prepared owner action, call prepareOwnerAction, then verifyPreparedOwnerAction with the original action and trusted OwnerActionContext (owner, mandate ID, original rent payer, and whether it has gas). Simulate the verified message on devnet, obtain the owner wallet signature, and call confirmOwnerAction with that same draft and signature. Poll until confirmed. Direct safety actions below remain available without GOL.

Execution and exact retries

Choose a cryptographically random 32-byte action ID once, persist it with the original intent, and reuse it as the idempotency key for both prepare and submit. A recipient is a wallet address; the engine transfers to its canonical USDC ATA. Prepare that ATA independently first. The Ed25519 agent signs the exact prepared message; the hosted submitter supplies the fee-payer signature.
Construct expected separately from the response: the original owner/agent, action ID, persisted sequence, checked configuration, and reviewed gas declaration (declaredRate, declaredPriorityLamports, maxCharge) or null. Do not copy an untrusted response wholesale into the verification context. The verifier checks intent, fee payer, instruction bytes, all accounts/privileges and signers. Use the same devnet simulation pattern as the quickstart before signing. Keep the agent signer local to your agent/server; GOL accepts its signature, not its key. The API durably stores accepted intent and signed transaction bytes. A timeout, restart, or indeterminate broadcast is not permission to create a second action ID. Poll execution(executionId) and retry the same ID, input, and signature. Stored signed attempts rebroadcast identical bytes and retain the same signature. After a genuinely expired unsigned attempt the same logical action can prepare a fresh attempt; inspect state and review its new bytes before signing. Action deadline and blockhash validity are separate bounds.

Finalized status and refusals

Use outcome (executed, refused, or reverted) to distinguish payment result from reimbursement state. collected alone does not mean a payment executed. Read signature, slot, feeLamports, refusalCode, settlement, and reconciliation. In this Solana path terminal observation uses finalized commitment, corroborated through the hosted independent RPC operators. It does not reuse Base’s safe semantics. API acknowledgement, successful simulation, and confirmed RPC inclusion do not prove finalized completion. No fixed observation latency is promised. An on-chain refusal is a successful transaction that emits a refusal, transfers no mandate payment, and preserves action counters and the executed replay bit. It can still charge eligible owner-approved gas. Refusals below code 40 (for example pause 5, revoke 6, disconnected grant/delegate 20, or epoch mismatch 22) are not chargeable. Policy refusals such as per-payment cap 67 can reimburse gas when all consent and payability checks pass. A reverted transaction rolls back program effects and has no later gas claim in this preview. refusals(mandateId) exposes code, rule tag, attempted value, remaining headroom and finalized signature. Never treat HTTP 202 as a payment receipt.

USDC gas reimbursement

The submitter pays network fees in SOL. Owner consent permits an inline USDC transfer to the approved fee recipient for successful execution and eligible on-chain refusal. The charge rounds up (signatureLamports + priorityLamports) * declaredRate / 1_000_000_000, then applies the execution max charge, per-action cap and remaining total cap. The declared rate is USDC base units per SOL. Initial hosted configuration declares 150000000 and permits at most 300000000; obtain current caps and rates from configuration and review them before signing. Payment budget and gas budget are distinct; both need USDC balance, SPL allowance, and active grant headroom. Unpayable gas is recorded without undoing an executed payment. Compare settlement.paid with reconciliation: actual finalized meta.fee, counted lamports, charged USDC, refund obligation, and shortfall are recorded separately. A charge above converted actual network cost creates a refund obligation; it is not proof an automatic refund has happened. The submitter absorbs a shortfall without a further owner charge. Conservative service fee reservations survive failures/restarts and are separate from the owner’s on-chain gas caps.

Direct owner safety actions

ownerSafetyInstruction builds a local instruction without the API. Supply independently checked owner/mandate/rent-payer identities. This example builds and simulates only; pass the returned transaction to the owner’s devnet wallet after an explicit review, broadcast its signed bytes through the same checked devnet RPC, wait for finalized status, and independently reread state. No key file or private key is accepted.
Use revoke_grant or spl_revoke to clean up partial setup. Use bump_epoch or invalidate for permanent invalidation rather than relying on disconnect. A safety action does not recall a transaction that finalized before it. Keep SOL available for fees and observe the final delegate/grant/epoch state independently. Disabling the hosted preview stops its submission and observer; it does not revoke on-chain authority or prevent an already signed transaction from landing.