/svs-action-authorization

SVS Action Authorization

Use SVS when a Solana agent proposes an action whose execution should be attributable, policy-checked, human-approved when required, and independently verifiable.

Safety boundary

• Never request, print, persist, or transmit a private key or raw signing secret.
• Never treat a badge, screenshot, transaction signature, or registry listing alone as authorization.
• Never execute the underlying Solana action before the SVS requirement passes.
• Reject stale, mismatched, revoked, wrong-network, or incomplete evidence.
• Keep wallet signing in the wallet. SVS receives signatures and proof references, not keys.

Agent workflow

1. Install the reviewed SDK version: npm install @svsprotocol/solana@0.4.0.
2. Construct the intended action without broadcasting it.
3. Check bot readiness before submission.
4. Submit the exact action through the signed SVS client.
5. Wait for the required human approval and production proof.
6. Execute or report success only after the returned proof matches the intended bot, controller wallet, action type, network, and action record.

import { SolanaVerificationClient } from "@svsprotocol/solana";

const svs = new SolanaVerificationClient({
  baseUrl: process.env.SVS_SERVER_URL,
  apiKey: process.env.SVS_BOT_API_KEY,
  requestSigningSecret: process.env.SVS_BOT_REQUEST_SIGNING_SECRET
});

const readiness = await svs.checkBotReadiness({
  botId: process.env.SVS_BOT_ID
});

if (readiness.ok !== true) {
  throw new Error(`SVS readiness failed: ${readiness.nextAction?.message ?? readiness.status}`);
}

const result = await svs.submitCertifiedActionAndWaitForProof({
  botId: process.env.SVS_BOT_ID,
  controllerWallet: process.env.SVS_CONTROLLER_WALLET,
  txType: "memo",
  payload: {
    memo: "agent action requiring authorization"
  }
});

if (result.ok !== true) {
  throw new Error(`SVS action proof failed: ${result.nextAction?.message ?? result.status}`);
}

Use a unique request nonce for each signed submission. Do not retry the same signed body after an ambiguous response unless the SDK's retry-safe status confirms it is safe. The bot API key and request-signing secret are scoped SVS credentials, not wallet keys; store them in a secret manager and rotate them through the documented credential lifecycle.

Protocol or wallet gate

The relying party independently checks identity and the exact action before accepting it:

import { requireAcceptedAction } from "@svsprotocol/solana/protocol";

const accepted = await requireAcceptedAction({
  baseUrl: process.env.SVS_SERVER_URL,
  apiKey: process.env.SVS_PROTOCOL_API_KEY,
  requestSigningSecret: process.env.SVS_PROTOCOL_REQUEST_SIGNING_SECRET,
  botId: expectedBotId,
  agentWallet: expectedControllerWallet,
  action: expectedActionType,
  actionRecordId,
  actionProofStaleAfterMs: 5 * 60 * 1000,
  checkReceiptRegistryChain: true
});

if (accepted.ok !== true || accepted.decision?.accepted !== true) {
  throw new Error("Reject unverified automation.");
}

When the agent has an official Solana Agent Registry asset, pass the registry client, asset, and expected network through agentRegistryIdentity. The operational wallet in that account must match the SVS controller wallet.

Evidence rules

Accept only when all required checks pass:

• Signed bot request and replay protection are current.
• The action payload, bot id, controller wallet, and network match the expected action.
• Required human approval is present and uses the current approval domain.
• Broadcast and custom receipt-registry evidence are confirmed on the expected network.
• The action proof is fresh under the relying party's policy.
• Official Agent Registry identity matches when that identity input is required.

Use the public integration review packet for current copyable examples: https://svsprotocol.com/integration-review.