@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.

When the Telaro REST is unreachable and this flag is on, gate returns a synthetic ApiAgentDetail with every field zeroed and is_mock: true set on both the top-level object and the nested agent object. The caller is expected to gate on is_mock explicitly.

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

v1 (always evaluated):

| 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. |

v2 (only when the matching policy field is set):

| Code | Meaning | |---|---| | DENYLISTED | Agent pubkey is in policy.denyList. Evaluated before the lookup. | | ACTION_NOT_ALLOWED | Action kind not in policy.allowedActionKinds. | | RATE_LIMITED | More than policy.rateLimit.maxCalls calls inside windowMs. | | OUTSIDE_TIME_WINDOW | Wall-clock outside policy.timeWindow.startUnixMs / endUnixMs. |

License

MIT — see LICENSE.