> ## 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.

# Solana preview quickstart

> Prepare, independently verify, simulate, sign, and confirm a bounded devnet USDC mandate with the exact published preview SDK.

This guide targets [Solana devnet Preview 1](https://docs.gol.network/examples/solana/index.md). Run the server example first to check credentials and configuration. Use the browser functions in your authenticated application to prepare a wallet review. They never accept an owner private key.

## Prerequisites

1. Obtain developer console access before [creating a test project and issuing a key](https://docs.gol.network/get-started/test-project.md). The console is behind a separate access gate. Use your own project UUID and a `gol_test_...` key with `project:read`, `accounts:read`, `mandates:read`, `mandates:write`, `actions:submit`, and `webhooks:manage` for this complete flow. Keep the key server-only. A live key is refused.
2. Use Node.js 22 or later and an ESM TypeScript application. Install the exact preview and both required optional peers explicitly:

```sh theme={null}
pnpm add @gol/sdk@0.9.0-solana-preview.1 @solana/kit@8.4.0 @solana/codecs-core@8.4.0
```

3. Connect an owner-controlled wallet advertising Wallet Standard `solana:devnet` and `solana:signTransaction`. Keep its keys in the wallet. This requirement is not a claim that any particular wallet/device is qualified.
4. Fund the owner with devnet SOL for setup fees, account rent, and later owner safety actions using the [Solana faucet](https://faucet.solana.com). Obtain devnet USDC from the [Circle faucet](https://faucet.circle.com), selecting **Solana Devnet**. Confirm the mint is `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU` and the owner's canonical associated token account exists and is not frozen. USDC uses six decimals: `100000` is 0.1 USDC. Fund enough for the reviewed payment total and gas allowance, not just the first payment.
5. Choose a separate test agent public key and recipient wallet address. The recipient's canonical USDC token account must also exist and be usable. Prepare it separately before an execution. An agent signs execution locally; it does not hold the owner's key. No owner, agent, or private RPC credential belongs in a browser bundle or in GOL's API.

Stable `latest` and `next` resolve to SDK `0.9.0`. Pin the preview version rather than using an unversioned install. If adding this to an existing Base application, isolate its dependency as a separate package so the root SDK resolution stays intact.

## Check the server connection

Set `GOL_TEST_API_KEY`, `GOL_PROJECT_ID`, and `GOL_OWNER_ADDRESS` through your server's environment or secret store. The owner address and project ID are public identities; the API key is secret. Do not use a `NEXT_PUBLIC_` variable for it.

```ts theme={null}
import { createSolanaApiClient } from "@gol/sdk/solana/server";

export async function checkPreview() {
  const client = createSolanaApiClient({
    baseUrl: "https://api.gol.network",
    projectId: process.env.GOL_PROJECT_ID!,
    apiKey: process.env.GOL_TEST_API_KEY!,
  });
  const configuration = await client.configuration();
  const owner = await client.owner(process.env.GOL_OWNER_ADDRESS!);
  return { configuration, owner };
}
```

`configuration()` verifies the devnet network, program identities, versions, and asset. The API owner snapshot is useful for display; the independent RPC read below supplies the signing context. Wire a browser `SolanaClient` to the [same-origin proxy](https://docs.gol.network/examples/solana/integration.md) before continuing.

## Prepare the exact owner review

Keep the original intent separately from the API response. This example permits 0.1 USDC per payment and 0.5 USDC in total for one hour. Gas consent adds the configuration's gas allowance separately; show its per-action cap, total cap, conversion rate, and fee recipient to the owner. Existing delegated/grant headroom is also carried forward separately from this new mandate's budget.

```ts theme={null}
import {
  readDevnetOwner, setupContext, verifyPreparedMandate,
  messageBase64, unsignedTransaction, SOLANA_DEVNET_GENESIS,
  type SolanaClient, type PrepareMandateInput,
} from "@gol/sdk/solana";

export async function prepareReview(
  client: SolanaClient, projectId: string,
  owner: string, agent: string, recipient: string,
) {
  const now = Math.floor(Date.now() / 1000);
  const input: PrepareMandateInput = {
    owner, agent, recipients: [recipient],
    maxPerActionBaseUnits: "100000", totalBaseUnits: "500000",
    validFrom: now, expiresAt: now + 3600, gas: true,
  };
  const configuration = await client.configuration();
  const independent = await readDevnetOwner(owner);
  const context = setupContext(projectId, configuration, input, independent, now);
  const prepared = await client.prepareMandate(input);
  const messages = await verifyPreparedMandate(prepared, input, context);
  async function rpc(method: string, params: unknown[]) {
    const response = await fetch("https://api.devnet.solana.com", {
      method: "POST", headers: { "content-type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
    });
    const data = await response.json();
    if (!response.ok || data.error) throw Error("Devnet RPC unavailable");
    return data.result;
  }
  if (await rpc("getGenesisHash", []) !== SOLANA_DEVNET_GENESIS)
    throw Error("Wrong RPC cluster");
  for (const message of messages) {
    const simulation = await rpc("simulateTransaction", [
      messageBase64(unsignedTransaction(message)),
      { encoding: "base64", sigVerify: false, commitment: "confirmed" },
    ]);
    if (simulation.value.err) throw Error("Simulation failed; do not sign");
  }
  return { input, independent, context, prepared, messages };
}
```

`readDevnetOwner` checks genesis and validates program-owned accounts, PDAs, sizes, discriminators, versions, owner/mint/engine identities, token balance, delegate and allowance at `finalized`. `setupContext` computes expected approval and grant amounts from that independent snapshot. `verifyPreparedMandate` recomputes terms, policy, gas consent and IDs and checks the complete instruction list, account privileges, signers and fee payer. Any mismatch stops the flow. It accepts the legacy messages this preview API prepares; lookup-table or alternate-message signing is not supported.

Show the original limits, exact total SPL approval, exact grant cap and expiry, carry-forward amounts, rent payer, gas consent and both transactions. Refresh expired reviews or changed wallet/state rather than modifying verified bytes. Simulation is a preflight, not a guarantee of later success or finality. Use bounded retry/backoff for RPC throttling; never open a wallet prompt after a failed check.

## Sign the batch and confirm

After the owner explicitly accepts the review, use a connected Wallet Standard signing feature. The account must advertise devnet. This function accepts that feature's `signTransaction` method and invokes it once with two inputs. A wallet can render the batch differently; actual prompt/display qualification is still pending.

```ts theme={null}
import { getTransactionDecoder, getBase58Decoder } from "@solana/kit";
import { unsignedTransaction, toHex, type SolanaClient } from "@gol/sdk/solana";

type Account = { address: string; chains: readonly string[] };
type Sign = (...inputs: {
  account: Account; chain: "solana:devnet"; transaction: Uint8Array;
}[]) => Promise<{ signedTransaction: Uint8Array }[]>;

export async function signAndConfirm(
  client: SolanaClient, draftId: string, messages: Uint8Array[],
  account: Account, signTransaction: Sign,
) {
  if (!account.chains.includes("solana:devnet") || messages.length !== 2)
    throw Error("Expected a devnet account and both setup messages");
  const signed = await signTransaction(...messages.map(message => ({
    account, chain: "solana:devnet" as const,
    transaction: unsignedTransaction(message),
  })));
  if (signed.length !== 2) throw Error("Incomplete batch; inspect state before retrying");
  const signatures = signed.map((result, index) => {
    const transaction = getTransactionDecoder().decode(result.signedTransaction);
    if (toHex(new Uint8Array(transaction.messageBytes)) !== toHex(messages[index]!))
      throw Error("Wallet changed the reviewed message");
    const signature = transaction.signatures[account.address as keyof typeof transaction.signatures];
    if (!signature || signature.every(byte => byte === 0)) throw Error("No owner signature");
    return getBase58Decoder().decode(signature);
  });
  // Submit the signatures, not a new transaction or a private key.
  for (let attempt = 0; attempt < 75; attempt++) {
    const result = await client.confirmMandate(draftId, signatures);
    if (result.draft.state === "confirmed") return result;
    if (["failed", "expired"].includes(result.draft.state))
      throw Error("Setup incomplete; inspect each transaction and clean up");
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  throw Error("Observation pending; retain this draft and signatures and poll again");
}
```

The API validates owner signatures and broadcasts the exact prepared messages. `confirmMandate` can return 202 while observation is pending; a confirmed draft means both setup transactions were observed at finalized commitment. Store the draft ID and signatures so a timeout resumes observation instead of creating another mandate. Read `client.mandate(mandateId)` and independently inspect the resulting state before executing.

## Partial setup cleanup

The batch is **not atomic**. Transaction 1 approves the SPL delegate and creates/widens an engine grant. Transaction 2 creates the mandate and optional gas policy. If only transaction 1 succeeds, authority remains installed even though this mandate was not created. Check each transaction's signature/state and read the owner state independently. Revoke the engine grant or SPL delegate before starting another review; these broader controls can affect other mandates sharing that grant/token account.

Use the [direct safety example](https://docs.gol.network/examples/solana/lifecycle.md#direct-owner-safety-actions) with `revoke_grant` or `spl_revoke`, a fresh devnet blockhash, successful simulation, and an owner wallet signature. Confirm the cleanup at finalized commitment and reread `readDevnetOwner`. SPL revoke is a disconnect: approving again can reconnect older active grants. Use `bump_epoch` or engine `invalidate` when permanent invalidation is intended. A timeout alone does not prove either transaction failed. Never blindly sign a second setup batch.


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