@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

10-second check: does this agent pass your bond/score policy?

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

const client = new TelaroClient(
  new Connection("https://api.devnet.solana.com"),
  Keypair.generate(),
);

const ok = await client.previewViewBond(
  new PublicKey("AgentPubkey..."),
  1_000_000_000n,  // minBond: 1000 USDC (atomic, 6dp)
  700,             // minScore
);
if (!ok) throw new Error("agent does not meet policy");

That is the read path. The write path (bonding, scoring, claims, builder yield) is in Quickstart. If you only need the gate check in one line, see @telaro/gate.

Starting from zero on devnet? The first section of the Quickstart walks from an empty machine to a registered, bonded agent in four shell commands plus one node script. Uses the live Telaro USDC faucet at https://www.telaro.xyz/api/faucet/usdc so there is no spl-token CLI step.

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 | | sponsor | findSponsorBondPda, effectiveBondAtomic, previewWithSponsorship, simulateSlashWaterfall (0.1.6+) | | strategy | canonicalStrategyBytes, strategyHash, evaluateStrategyMatch, findStrategyViolations (0.1.7+) |

Sponsor bonds (off-chain SDK surface)

Two parties bond the same agent. When a slash lands, the agent absorbs first, then sponsors in order of createdAt, then the InsuranceVault takes the tail. The off-chain functions let a DApp preview a gate verdict that includes sponsor deposits, and let a sponsor UI render the slash waterfall ahead of time.

import {
  effectiveBondAtomic,
  previewWithSponsorship,
  simulateSlashWaterfall,
} from "@telaro/sdk";

const effective = effectiveBondAtomic({
  selfBond: 1_000_000_000n,
  reserved: 0n,
  sponsorBonds: [
    { sponsor: sponsorA, amountAtomic: 2_000_000_000n, createdAt: 1 },
    { sponsor: sponsorB, amountAtomic: 1_500_000_000n, createdAt: 2 },
  ],
});
// → 4_500_000_000n (1k agent + 2k A + 1.5k B)

const fail = previewWithSponsorship({
  agentScore: 720,
  selfBond: 1_000_000_000n,
  reserved: 0n,
  sponsorBonds: [...],
  minBondAtomic: 3_000_000_000n,
  minScore: 700,
  frozen: false,
});
// → null on pass, or { code: "BOND_BELOW_MIN", ... } on fail

const waterfall = simulateSlashWaterfall({
  slashAtomic: 2_500_000_000n,
  selfBond: 1_000_000_000n,
  sponsorBonds: [...],
  insuranceVaultAtomic: 5_000_000_000n,
});
// → { agentTook, sponsorTook[], insuranceVaultTook }

The on-chain SponsorBond account + three sponsor instructions ship with the next audit batch; the off-chain shape pinned here is the authoritative pre-spec.

Strategy declaration (perp DEX gate)

An agent declares ahead of time the envelope of behaviour it will operate within (max leverage, max position, allowed assets, allowed venues, action kinds, 30d loss budget). A venue stores the canonical sha-256 hash on its gate account and rejects orders outside the envelope.

import {
  canonicalStrategyBytes,
  strategyHashHex,
  evaluateStrategyMatch,
  findStrategyViolations,
  type StrategyDeclaration,
} from "@telaro/sdk";

const strategy: StrategyDeclaration = {
  schemaVersion: "telaro/strategy/v1",
  agent,
  controller,
  nonce: 1,
  validFromUnixSec: now,
  validUntilUnixSec: now + 30 * 86400,
  maxLeverage: 5,
  maxPositionSizeAtomic: 50_000_000_000n, // $50k
  riskBudgetUsdcAtomic: 10_000_000_000n,  // $10k / 30d
  allowedAssets: [USDC],
  allowedVenues: [DRIFT],
  allowedActionKinds: [ActionKind.Swap, ActionKind.Stake],
};

const hash = strategyHashHex(strategy);
// Store `hash` on the venue's gate account.

const violation = evaluateStrategyMatch(action, strategy, {
  realisedLoss30dAtomic: agentRunningLoss,
});
if (violation) throw new Error(`gate ${violation.code}: ${violation.message}`);

const evidence = findStrategyViolations(actionHistory, strategy);
// Itemised list, ready to attach to a dispute claim.

For a full runnable demo (six reject codes + bulk walk) see examples/strategy-aware-agent. The on-chain declare_strategy instruction ships with the next audit batch; the canonical byte layout is pinned now so anything wired against this surface today round-trips when the ix lands.

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.