Sentinel

What it does

Sentinel evaluates configured execution policy. It can check declared intent metadata, or decode and simulate the exact supported SOL/original SPL-token payment that a wallet is about to approve.

Use it before wallet authority, not instead of it. A passing result always has authorises: false. Its decision applies to the checked inputs and policy digest; it is not a reusable approval for changed bytes, a prediction of trade profitability or proof of future settlement.

Use independently

Select uk.capp.sidecar.solana-sentinel. Choose local-policy to test declared metadata without RPC, or conduit-peer for exact payment/simulation checks. The owner API is window.capp.solana.sentinel; the portable client does not add policy enforcement of its own.

Inspect the returned checks and violations, not just whether a promise resolved. evaluate() and preflight() are aliases in this provider; calling the latter with only metadata does not magically add instruction verification.

Provider dependencies

Edge's devnet flow requires the Conduit-backed exact-byte path. It refuses a merely allowed metadata result without transactionInstructionsVerified and simulationBindsExactBytes.

First successful metadata check

Configure local policy for devnet with the System Program allowed, a small amount/fee ceiling and no mandatory simulation for this metadata-only rehearsal. Leave the exact-SOL-transfer option off for that rehearsal only; do not weaken a live payment build to run it.

Copy the client module alongside the example module. The helper is inert until called and cannot sign/send.

import {createSolanaClient} from './solana-client.mjs';
const client = createSolanaClient(() => window.capp?.solana);

export async function checkDeclaredPayment({recipient, amountLamports, feeLamports}) {
  const status = await client.call('sentinel', 'status');
  if (!status.ready || status.providerMode !== 'local-policy' || status.network !== 'devnet') {
    throw new Error('Use a local-policy devnet rehearsal');
  }
  return client.call('sentinel', 'evaluate', {
    intent: {kind: 'payment', network: 'devnet', recipient, amountLamports,
      createdAt: Date.now() / 1000, executable: true},
    feeLamports, slippageBps: 0, riskTier: 'low',
    programIds: ['11111111111111111111111111111111']
  });
}

Use a real public recipient address in your application even though this metadata path does not authenticate it. With values inside the configured ceilings, expect an allowed decision, authorises: false, metadataVerified: false, no simulation and no verified transaction instructions. Raise the amount above the configured ceiling and expect allowed: false with amount in violations.

Exact-byte preflight

For a supported real payment, provide the saved intent, walletPubkey, messageBytesBase64, messageDigest, complete unsigned transactionBase64, current feeLamports, slippage/risk inputs and the actual programIds. A message is not the same as a transaction envelope. Prefer Edge for constructing and retaining this set.

Inspect all of the following before wallet approval: allowed, matching messageDigest, policyDigest, transactionInstructionsVerified, simulationBindsExactBytes and relevant token/account checks. simulation.value.err: null alone is insufficient if it concerns different bytes or omits the required account/amount policy.

For native SOL, exact mode checks sender, recipient, amount, declared programs and the transaction's message. For tokens, the asset must identify the original Token Program, mint, decimals and exact string amountAtomic. It additionally observes token account/mint state, source funds, recipient associated-account requirements, fee estimate and SOL available for fee/rent. Configure maxAccountRentLamports separately from token amount and fee ceilings.

Policy choices and time

Freshness uses seconds, with the configured maximum age and a small tolerated future-clock offset. Position intents require a timestamp. Keep the originally accepted intent/time while reviewing; do not continuously manufacture a new timestamp to make an old instruction look fresh.

Position classifications and risk-reducing bypasses are caller-supplied metadata. allowRiskReducingCloseBypass deliberately relaxes the amount ceiling for a declared reduction with a position identity; it does not independently verify that the position exists or that an instruction actually reduces risk. Keep it off unless your trusted application/provider establishes that meaning.

Scope and limitations

Token preflight requires Conduit, a configured per-mint atomic ceiling, verified mint/account state, sufficient SOL fees/rent, and simulation of the exact bytes. A policy pass never grants wallet authority.

Local metadata checks cannot validate an arbitrary protocol, swap, oracle or trade. Original-token restrictions are intentional; unsupported Token-2022, wrapped SOL or unknown instruction layouts are not “almost supported.” A downstream wallet must enforce its own current policy and exact request binding even when Sentinel passed earlier.

Application API

The owning interface is window.capp.solana.sentinel. The portable client calls the same methods. This table describes main arguments, not a stricter typed guarantee than the current provider implements. Exact transaction/provider bindings must be preserved; unsupported state or arguments are rejected.

import {createSolanaClient} from './solana-client.mjs';
const client = createSolanaClient(() => window.capp?.solana);
const status = await client.call('sentinel', 'status');

status

client.call('sentinel', 'status', input)

Main input: No arguments required.

Read policy-provider readiness and configured verification limits.

evaluate

client.call('sentinel', 'evaluate', input)

Main input: intent, feeLamports, slippageBps, riskTier, programIds; optional messageDigest, messageBytesBase64 and transactionBase64.

Evaluate declared policy. Metadata-only checks are distinct from exact-byte verification and never grant wallet authority.

preflight

client.call('sentinel', 'preflight', input)

Main input: intent, walletPubkey, messageDigest, messageBytesBase64, transactionBase64, feeLamports, programIds, slippageBps and riskTier.

Decode and simulate supported payment bytes through the selected provider. Enforce asset, fee, rent and per-mint limits. Use Edge for the complete prepared-operation argument binding.

Troubleshooting

Verify your integration

Test amount/fee/rent ceilings, unknown programs, stale intents, wrong sender/recipient, altered message bytes, failed RPC simulation and unsupported tokens. Verify that a passing local metadata test is never accepted as an exact live-payment preflight.

Integration recipes

Composition · Devnet payment · Recovery · Typed client · Schemas

Related data contracts

These schemas describe payload shape, not evidence of approval or successful execution. Match the version in your payload; older versions remain listed for compatibility.

• capp.solana-intent.v2.schema.json
• capp.solana-policy-result.v1.schema.json
• capp.solana-signing-policy.v1.schema.json

Configuration reference

These are the selected package's configuration fields. String credential values and installation-specific defaults are never published here. A field's presence does not bypass its runtime policy.

Agent interfaces

These names are declared by the package for host/Agent integration, not JavaScript methods to invoke directly. The host must register a tool, grant its scope and enforce its approval policy. A manifest declaration alone does not prove availability in every Agent catalogue. Prefer the application API above when integrating your own app.