@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