@telaro/gate

One-line trust gate for AI agents on Solana.

Verifies that an agent meets your bond + score policy before you delegate capital to it. Throws if the agent isn't bonded, score too low, bond too small, or frozen.

npm install @telaro/gate

The whole API

import { gate } from "@telaro/gate";

await gate("AgentPubkey...", {
  minBond: 1_000_000_000n,  // 1000 USDC (atomic, 6dp)
  minScore: 700,
});
// → throws TelaroGateError on failure
// → returns trust profile on success

That's the integration. Wrap your delegate(capital) / accept_deposit() / place_order() call in gate(...) and you're done. Default fails closed — if Telaro REST is unreachable, the call throws so you never delegate to an unverified agent.

Common patterns

Drop-in before a delegation

import { gate, TelaroGateError } from "@telaro/gate";

async function delegateCapital(agentPubkey: string, amountUsdc: bigint) {
  try {
    await gate(agentPubkey, { minBond: 5_000_000_000n, minScore: 750 });
  } catch (err) {
    if (err instanceof TelaroGateError) {
      console.warn(`refused delegation: ${err.code}`);
      return;
    }
    throw err;
  }
  // safe to delegate — agent is bonded, scored, and not frozen
  await yourVault.deposit(agentPubkey, amountUsdc);
}

Non-throwing variant

import { tryGate } from "@telaro/gate";

const result = await tryGate(agentPubkey, {
  minBond: 5_000_000_000n,
  minScore: 750,
});
if (!result.ok) {
  return { error: result.code, message: result.reason };
}
console.log(`score=${result.trust.agent.score}`);

Telemetry hook

await gate(agentPubkey, policy, {
  onDecision(event) {
    metrics.record("telaro.gate", {
      decision: event.decision,
      code: event.code,
      durationMs: event.durationMs,
    });
  },
});

Custom endpoint / API key

await gate(agentPubkey, policy, {
  apiBase: "https://telaro.xyz",   // default
  apiKey: process.env.TELARO_API_KEY,
  cacheTtlMs: 60_000,              // 30s default
});

Degraded-mode fallback (advanced)

Only set allowOnLookupFailure: true if your downstream call is reversible or idempotent. Otherwise you risk delegating capital with no trust info.

const trust = await gate(agentPubkey, policy, {
  allowOnLookupFailure: true,
});
if (trust.is_mock) {
  console.warn("telaro lookup failed — proceeding in degraded mode");
}

Choosing between @telaro/* packages

| Package | When to use | |---|---| | @telaro/gate | You want one explicit check before delegating. Start here. | | @telaro/middleware | You want to wrap an entire third-party SDK so every method is auto-gated. | | @telaro/sdk | You want full read+write access (register, record actions, file claims). | | telaro-gate (Rust) | You want on-chain CPI gating from your own Anchor program. |

Failure codes

| Code | Meaning | |---|---| | NOT_BONDED | No on-chain agent record found. | | BOND_BELOW_MIN | Agent's current bond is below minBond. | | SCORE_BELOW_MIN | Agent's score is below minScore. | | FROZEN | Agent is frozen (open dispute, slashed below floor, etc.). | | LOOKUP_FAILED | Telaro REST was unreachable. Fails closed by default. |

License

MIT — see LICENSE.