@telaro/sdk

TypeScript SDK for the Telaro protocol on Solana. A bonded reputation primitive for AI agents. Currently targets Solana devnet. Mainnet is pending audit.

📦 @telaro/sdk on npm · 🌐 telaro.xyz · 📚 Quickstart · 📖 Main repo

Install

npm install @telaro/sdk @solana/web3.js @solana/spl-token

Other package managers also work: yarn add, pnpm add, bun add.

⚠️ Required: pin rpc-websockets

@solana/[email protected] pulls a rpc-websockets build whose transitive uuid@14 (ESM-only) breaks a CJS shim. You'll hit ERR_REQUIRE_ESM at the first import. Add this to your package.json before running npm install:

{
  "overrides": {
    "rpc-websockets": "9.1.1"
  }
}

pnpm and yarn users: use "pnpm": { "overrides": ... } / "resolutions": { ... } in the same shape. Node ≥22 fixes this natively, so you can skip the override if you're on Node 22+. This is a Solana ecosystem-wide issue, not specific to Telaro.

Requirements

• Node ≥ 20 (recommended: ≥ 22 to skip the override above)
• ESM project ("type": "module" in package.json or .mts files)
• Compatible runtimes: Next.js 15+, Vite, Bun, Deno, Anchor 0.30+ TS templates, modern Node
• Not compatible: legacy CommonJS-only environments. Use a dynamic await import("@telaro/sdk") if you must call from CJS.

Quick start: agent side (framework integrator)

import { TelaroClient, ActionKind, ActionOutcome } from "@telaro/sdk";
import { Connection, Keypair, PublicKey } from "@solana/web3.js";

const conn = new Connection("https://api.devnet.solana.com", "confirmed");
const controller = Keypair.fromSecretKey(/* ... */);
const rep = new TelaroClient(conn, controller);

// 1. Register the agent + post bond.
await rep.registerAgent({
  framework: "sendai",
  metadataUri: "https://my-agent.example/metadata.json",
  scorer: new PublicKey("ScorerPubkeyOfTheIndexer..."),
  bondMint: new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"), // USDC
  bondAmount: 100_000_000n, // 100 USDC
});

// 2. Record actions as the agent acts.
await rep.recordAction({
  payload: { type: "swap", in: "SOL", out: "USDC", amount: 1.0 },
  kind: ActionKind.Swap,
  outcome: ActionOutcome.Success,
  valueAtomic: 50_000_000n, // ≈ $50 value-at-risk
});

Quick start: DApp side (consumer)

import { findAgentPda, computeScore, tierOf } from "@telaro/sdk";

// Read agent state from chain (use Anchor account decoder or direct fetch).
// Then locally compute / verify the score:
const { score, components } = computeScore({
  actionCount: 412n,
  successCount: 401n,
  disputedCount: 1n,
  currentBond: 5_247_000_000n,    // $5,247
  valueHandled30d: 21_000_000_000n,
});

if (tierOf(score) === "high" && score >= 700) {
  // OK to delegate.
}

Quick start: DApp on-chain enforcement (Anchor CPI)

In your own Anchor program, before delegating capital to an agent, invoke view_bond on the Telaro program. Reverts if the agent doesn't meet your policy:

use telaro::cpi::{view_bond, accounts::ViewBond};

view_bond(
    CpiContext::new(telaro_program, ViewBond { agent: agent_account.into() }),
    1_000_000_000u64,  // min_bond = 1000 USDC
    700u16,            // min_score
)?;
// If we reach here, the agent meets the policy. Delegate safely.

API surface

| Module | Exports | |---|---| | client | TelaroClient, TelaroClientOptions | | instructions | build*Ix for each instruction (composable) | | pda | findAgentPda, findClaimPda, findBondVaultPda, … | | score | computeScore, tierOf, ScoreInputs, ScoreOutput | | types | AgentAccount, ActionKind, ActionOutcome, ClaimStatus, … | | format | formatUsdc, formatPercent, formatRelativeTime, … | | constants | PROGRAM_ID, MIN_BOND_USDC, CLAIM_*, … | | hash | hashAction(payload) deterministic action_hash |

Scoring policy (default, v1)

score = 500
       + 50  × tanh(log10(action_count))                  // tenure
       + 200 × (success / action)                          // success rate
       - 300 × (disputed / action)                         // disputes
       + 100 × min(1.0, bond / value_handled_30d)         // skin in the game
       - 100 if recent_high_value_failure_in_7d           // hot incident decay
clamp(0, 1000)

The bondRatioBps returned alongside the score is what the on-chain update_score instruction emits, allowing consumers to verify the policy.

License

MIT. See LICENSE.