@sinai-standard/routes

@sinai-standard/routes

Lockstep Routes integration for Sinai Standard — AI agent transaction enforcement.

What This Does

When an AI agent issues or manages regulated tokens via Sinai Standard, every transaction passes through Lockstep Routes' 13-step enforcer pipeline before hitting the Solana network.

This creates double enforcement:

Layer	Where	What
Lockstep Routes	Agent-side (off-chain)	Program whitelist, transfer limits, rate limits, operating hours, spend caps
Transfer Hooks	Protocol-side (on-chain)	Allowlist checks, tax collection, hold periods, max balance caps

Routes catches unauthorized transactions before they cost gas. Transfer Hooks enforce compliance on-chain even if an agent bypasses Routes. Together they form a defense-in-depth model for AI-managed token operations.

Quick Start

import { Keypair } from "@solana/web3.js";
import {
  createDefaultSpec,
  SinaiRoutesGuard,
} from "@sinai-standard/routes";

// Owner signs the spec; agent operates within its bounds
const ownerKeypair = Keypair.fromSecretKey(/* ... */);
const enforcerKeypair = Keypair.generate();
const agentWallet = Keypair.generate();

// 1. Generate a RouteSpec with sensible defaults
const spec = createDefaultSpec(
  "my-treasury-agent",
  agentWallet.publicKey.toBase58(),
  ownerKeypair,
);

// 2. Create the guard
const guard = new SinaiRoutesGuard(
  spec,
  "https://api.devnet.solana.com",
  enforcerKeypair,
  agentWallet.publicKey,
);

// 3. Validate before sending
const result = await guard.validateTransfer(transferTx);
if (result.allowed) {
  // send the transaction
} else {
  console.error("Blocked:", result.reason);
}

// 4. Compliance reporting
const receipts = await guard.getAuditTrail();
const stats = guard.getAgentStats();

Custom RouteSpec

Use generateSinaiRouteSpec for full control over limits and policies:

import { generateSinaiRouteSpec } from "@sinai-standard/routes";

const spec = generateSinaiRouteSpec({
  agentId: "compliance-bot-1",
  agentWallet: agentPubkey.toBase58(),
  ownerKeypair,
  options: {
    // Token limits (raw amounts, accounting for decimals)
    maxTransferAmount: BigInt(500_000) * BigInt(10 ** 6),
    maxDailyVolume: BigInt(2_000_000) * BigInt(10 ** 6),

    // Fee budget
    maxDailySpendLamports: BigInt(2) * BigInt(10 ** 9), // 2 SOL

    // Rate limits
    maxTxPerMinute: 10,
    maxTxPerHour: 200,

    // Operating hours (UTC) — null for 24/7
    allowedHoursUtc: [8, 20], // 8 AM to 8 PM UTC

    // Auto-freeze threshold
    autoFreezeAfterViolations: 5,

    // Extra programs (e.g., your own CPI targets)
    additionalPrograms: [
      { programId: "YourProgram...", allow: true, label: "Custom", maxCallsPerTx: 1 },
    ],

    // Accounts the agent must never touch
    forbiddenAccounts: ["TreasuryMultisig..."],
  },
});

Whitelisted Programs

The default spec whitelists these programs:

Program	Address
Sinai Token Factory	VXQL8u4NVUYG1zaejujwh5gr21iinmk4yYCXn1g9TXr
Sinai Allowlist Hook	Bo3Rd8qZeuxU1cmtCqKEFPRe5Uumx9tusjZ7B1hXtPgc
Sinai Tax Hook	ACJXvcH4uaBfBwSwcVG48zJ177ydEvtCqGRMKXv53goZ
Sinai Hold Hook	8HkukxWoo27BnNwqCzCim4ueKaGEfqLW4LdSZkHkCWzS
Sinai Router Hook	HHnt7Hfnp2fDftFNCFPqEhebgXGizuqubXqhiEi8C1of
Sinai Max Balance Hook	Ctx9ZtNzPFYyjqxdZSMYLgHdqNNpAS61G6ok1dYVBHWi
Token-2022	TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
System Program	11111111111111111111111111111111
Associated Token Program	ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL

Emergency Controls

// Immediately halt all agent operations
guard.freeze();

// Resume
guard.unfreeze();

// Check status
guard.isFrozen; // boolean

API Reference

createDefaultSpec(agentId, agentWallet, ownerKeypair)

Quick start with sensible defaults (1M token transfer cap, 10M daily volume, 5 SOL fee budget, 30 tx/min).

generateSinaiRouteSpec(config)

Full control over the RouteSpec. See SinaiRouteSpecOptions for all options.

SinaiRoutesGuard

• validateTokenCreation(tx) — Validate a token creation transaction
• validateTransfer(tx) — Validate a token transfer
• validateAdminAction(tx) — Validate config changes (tax, allowlist, etc.)
• getAuditTrail() — Get the receipt chain for compliance reporting
• getAgentStats() — Daily tx count, spend, blocked count
• freeze() / unfreeze() — Emergency controls