SDK Reference

Two clients.One attestation layer.

prova-agent-sdk v0.1.6 ships two independent clients. ProvaClient writes receipts on-chain via Solana. ProvaApiClient queries the indexed data via REST — no wallet required.

npm install prova-agent-sdk

v0.1.6 · Apache 2.0 · Node 18+

On-chain

ProvaClient

Writes signed BehaviorAttestation accounts to Solana via the Anchor program. Requires an agent keypair and an RPC URL.

Constructor

import { ProvaClient } from 'prova-agent-sdk';
import { Keypair } from '@solana/web3.js';

const client = new ProvaClient({
  rpcUrl: 'https://devnet.helius-rpc.com/?api-key=...',
  agentKeypair: Keypair.fromSecretKey(secretKeyBytes),
});

Methods

attest(builder: AttestationBuilder): Promise<AttestationReceipt>
Submits an attestation transaction to Solana. Returns the PDA address and transaction signature.
verify(pda: string): Promise<{ valid: boolean; attestation?: ... }>
Fetches the on-chain account and verifies the Ed25519 signature.

AttestationBuilder helpers

AttestationBuilder.transaction(txSig, metadata?)
Wraps a Solana transaction signature.
AttestationBuilder.toolCall(tool, params, metadata?)
Records an LLM tool invocation.
AttestationBuilder.decision(type, rationale, metadata?)
Records an agent decision with rationale.

REST API

ProvaApiClient

Queries the Prova indexer (Postgres-backed) over HTTP. Read-only. No wallet or Solana dependency.

Constructor

import { ProvaApiClient } from 'prova-agent-sdk';

const api = new ProvaApiClient({
  apiUrl: 'https://prova-api.fly.dev',
  apiKey: 'prova_...',   // optional — required for premium endpoints
});

Methods

listAttestations(query?)
Paginated list. Filter by agentPda, actionType, from/to dates.
getAttestation(pda)
Single attestation by PDA address.
verifyAttestation(pda)
Returns { valid, attestation?, error? } without throwing.
getAgent(agentId)
Agent profile: operator, registration date, attestation count.
getAgentStats(agentId)
Breakdown by action type + recent attestations.
bulkVerify(ids[]) ⚡ premium
Verify up to 1 000 attestation IDs in one call. Requires API key.
getFullHistory(agentId) ⚡ premium
Complete attestation history for an agent. Requires API key.
getForensicReport(agentId) ⚡ premium
PDF-ready summary with timeline. Requires API key.

Key types

// Returned by attest()
interface AttestationReceipt {
  id: string;          // PDA address on Solana
  txSignature: string; // Solana transaction signature
}

// Returned by listAttestations()
interface AttestationResponse {
  pda: string;
  agentPda: string;
  actionType: string;
  actionHash: string;
  timestamp: string;   // ISO 8601
  blockHeight: number;
  privacyMode: boolean;
  signature: string;
  schemaVersion: number;
}

// Returned by getAgentStats()
interface AgentStatsResponse {
  agent: AgentResponse;
  totalAttestations: number;
  byType: Record<string, number>;
  recentAttestations: AttestationResponse[];
}

Full example

import { ProvaClient, ProvaApiClient, AttestationBuilder } from 'prova-agent-sdk';
import { Keypair } from '@solana/web3.js';

// 1 — write on-chain
const client = new ProvaClient({
  rpcUrl: process.env.SOLANA_RPC_URL!,
  agentKeypair: Keypair.fromSecretKey(agentSecretKey),
});

const receipt = await client.attest(
  AttestationBuilder.transaction(txSig, { operation: 'transfer', amount: 100 })
);

// 2 — query via REST
const api = new ProvaApiClient({
  apiUrl: process.env.PROVA_API_URL!,
  apiKey: process.env.PROVA_API_KEY,
});

const { valid } = await api.verifyAttestation(receipt.id);
console.log('Tamper-proof:', valid); // true