> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gol.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle, execution, and owner safety

> Mandate states, exact execution review, refusal and gas semantics, finalized observation, and direct on-chain owner actions.

This guide applies only to [Solana devnet Preview 1](https://docs.gol.network/examples/solana/index.md). 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

| State/control | Effect |
| - | - |
| `active` | The agent may attempt the approved transfer within all limits and valid times |
| `paused` / `pause` | Stops execution until the owner resumes |
| `resume` | Re-enables a paused mandate; cannot undo revocation, expiry, or epoch invalidation |
| `revoked` / `revoke` | Permanently ends this mandate's execution authority |
| `expired` | The mandate's expiry has passed |
| `revoke_gas_policy` | Stops reimbursement under that gas policy without widening transfer authority |
| `revoke_grant` | Revokes the shared engine grant for this owner and mint; affects mandates using it |
| `bump_epoch` | Permanently invalidates grants/mandates bound to the old authority epoch |
| `invalidate` | Permanently invalidates mandates bound to the owner's old engine epoch |
| `spl_revoke` | Disconnects the token delegate; later reapproval can reconnect old active grants |
| `closed` / `close` | Reclaims mandate and optional gas-policy rent after revocation/expiry and the approval window |

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.

```ts theme={null}
import {
  verifyPreparedExecution, type SolanaClient,
  type PrepareExecutionInput, type ExecutionContext,
} from "@gol/sdk/solana";

export async function submitReviewedExecution(
  client: SolanaClient, input: PrepareExecutionInput,
  expected: ExecutionContext,
  simulate: (message: Uint8Array) => Promise<void>,
  signAgent: (message: Uint8Array) => Promise<string>,
) {
  const prepared = await client.prepareExecution(expected.actionId, input);
  const message = await verifyPreparedExecution(prepared, input, expected);
  await simulate(message); // Devnet genesis check and failed-simulation rejection.
  const agentSignature = await signAgent(message); // Local agent signer; base58 signature.
  return client.submitExecution(expected.actionId, agentSignature);
}
```

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

| Execution state | Meaning |
| - | - |
| `accepted` | Prepared for an agent signature |
| `signed`, `broadcast`, `indeterminate` | Durable submission/observation in progress; outcome is not final |
| `expired` | This attempt is no longer landable and no confirmed receipt was found; inspect before retrying |
| `collected` | Finalized receipt observed and inline USDC reimbursement paid |
| `uncollectable` | Finalized receipt observed with an unpaid inline gas settlement |
| `not_charged` | Finalized receipt observed without a paid gas settlement, including a reverted transaction |

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.

```ts theme={null}
import { createSolanaRpc } from "@solana/kit";
import {
  ownerSafetyInstruction, buildMessage, unsignedTransaction, messageBase64,
  SOLANA_DEVNET_GENESIS, type OwnerAction, type OwnerActionContext,
} from "@gol/sdk/solana";

export async function directSafety(action: OwnerAction, context: OwnerActionContext) {
  const rpc = createSolanaRpc("https://api.devnet.solana.com");
  if (await rpc.getGenesisHash().send() !== SOLANA_DEVNET_GENESIS)
    throw Error("Wrong cluster");
  const { value: lifetime } = await rpc.getLatestBlockhash({ commitment: "finalized" }).send();
  const instruction = await ownerSafetyInstruction(action, context);
  const message = buildMessage(context.owner, lifetime.blockhash, [instruction]);
  const transaction = unsignedTransaction(message);
  const { value } = await rpc.simulateTransaction(messageBase64(transaction) as Parameters<typeof rpc.simulateTransaction>[0], {
    encoding: "base64", sigVerify: false, commitment: "confirmed",
  }).send();
  if (value.err) throw Error("Safety action simulation failed");
  return { message, transaction, lastValidBlockHeight: lifetime.lastValidBlockHeight };
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.