@telaro/ars-solana

The Agentic Risk Standard (ARS), implemented for the Telaro Solana program.

ARS splits a job into a fee track and a principal track. Telaro implements the principal track — the underwriting → collateral → principal-release lifecycle for AI agents that handle user capital.

What's here

| Module | Role | | ------ | ---- | | events.ts | the principal-track event types — the job log is append-only | | state.ts | the event-sourced state machine — replay() derives the job | | store.ts | EventStore — append-only, validate-on-append event log | | ingest.ts | toArsEvent — telaro on-chain events → ARS events | | settlement.ts | the SettlementLayer contract + telaro instruction map | | binding.ts | ARS settlement actions → telaro instructions (pure builders) | | client.ts | TelaroSettlement — the async client that sends them |

Lifecycle

A job's state is derived by replaying its event log — there is no mutable state to corrupt, matching the ARS reference design.

AWAIT_UNDERWRITING → UNDERWRITING → RELEASABLE → EXECUTING
                          │              → EVIDENCE_SUBMITTED
                          │                    → (DISPUTED →) CLOSED
                          └─ REJECTED

import { replay } from "@telaro/ars-solana";

const job = replay([
  { type: "JobOpened", jobId, at, agent, requestor, exposureAtomic },
  { type: "UnderwritingStarted", jobId, at },
  { type: "UnderwritingDecided", jobId, at, passed: true },
  { type: "PrincipalReleased", jobId, at, amountAtomic },
  { type: "EvidenceSubmitted", jobId, at, actionHash, outcome: "success" },
  { type: "Closed", jobId, at, resolution: "no_dispute" },
]);
// job.state === "CLOSED"

An illegal transition throws ARSTransitionError — the log can never fold into an invalid job.

SettlementLayer

settlement.ts pins the ARS SettlementLayer contract for Solana. Of the 8 ARS methods, 6 map onto telaro program instructions that already exist on-chain (TELARO_SETTLEMENT_MAP); the two *Fee methods are out of scope for v1 — Telaro is a capital-risk layer, not a generic service-fee escrow.

binding.ts is the on-chain binding — lockCollateralIx, slashCollateralIx, unlockCollateralIx, payPremiumIx and releasePrincipalIx each turn an ARS settlement action into a telaro TransactionInstruction (built via @telaro/sdk):

import { releasePrincipalIx } from "@telaro/ars-solana";

const ix = releasePrincipalIx({ jobId, agent, controller, amountAtomic });
// → a request_credit instruction; add it to a Transaction, sign, send.

client.ts is the async settlement client — TelaroSettlement implements the SettlementLayer interface, building each binding instruction and sending it:

import { TelaroSettlement, connectionSender } from "@telaro/ars-solana";

const settlement = new TelaroSettlement({ sender: connectionSender(connection) });
const { signature } = await settlement.releasePrincipal(
  { jobId, agent, controller, amountAtomic },
  [controllerKeypair], // signers, fee payer first
);

Sending is abstracted behind a TxSender, so the same client runs against a live RPC (connectionSender) or an in-process bankrun runtime. The binding instructions are verified end to end against the real telaro.so — see programs/telaro/tests/tests/ars-binding.test.ts.

License

MIT