npm package: @sinai-standard/routes
Description: Lockstep Routes integration for Sinai Standard — AI agent transaction enforcement
Latest version: 0.1.0

# @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](https://github.com/lockstep-ai/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

```typescript
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:

```typescript
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

```typescript
// 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