Beni's policies compile to a Cardano validator. A transaction that breaks the
rules never settles — no warning, no signed message, no log to ignore.
Just rejection.
);
}
function SecurityLayers() {
const layers = [
{ n: "L4", t: "The operator", d: "Human-in-the-loop approvals, freeze, role-based access.", who: "you" },
{ n: "L3", t: "The policy engine", d: "Rule composition, simulation, audit log, history.", who: "beni cloud" },
{ n: "L2", t: "The validator", d: "On-chain enforcement of every rule, written in Aiken.", who: "cardano" },
{ n: "L1", t: "Cardano", d: "Settlement. Atomic, public, irreversible.", who: "cardano" },
];
return (
I. Defense in depth
Four layers between an agent and your money.
Each layer is independent. A bug in the dashboard cannot reach the validator.
A compromised validator cannot reach the L1. Cardano's deterministic
execution turns rule violations into outright rejection.
each layer fails closed, never open.
{layers.map((l, i) => (
{l.n}
{l.t}
{l.d}
{l.who}
))}
↑ closer to the user · closer to the chain ↓
);
}
function ContractAnatomy() {
return (
II. The validator, opened up
Every spend, checked four ways.
{/* Aiken code */}
VALIDATORS/BENI_GUARD.AKAIKEN
{`validator beni_guard(params) {
spend(d: Datum, r: Redeemer, ctx) -> Bool {
let total = sum_value(ctx.tx.outputs)
// 1. Per-transaction cap
expect total <= d.per_tx_cap
// 2. Rolling daily cap
expect d.day_spent + total <= d.daily_cap
// 3. Whitelist OR approval token
expect in_whitelist(ctx, d.whitelist)
|| has_approval_token(ctx, params.thread)
// 4. Freeze guard
expect !d.frozen
True
}
}`}
{/* Pipeline */}
The pipeline
Step by step.
{[
{ s: "Inputs gathered", d: "agent UTxO + datum + thread token" },
{ s: "Cap checks", d: "per_tx_cap and daily_cap" },
{ s: "Whitelist check", d: "recipient in allowed_addresses" },
{ s: "Approval path", d: "owner signature for above-cap spends" },
{ s: "Freeze guard", d: "datum.frozen must be false" },
{ s: "Accepted, or rejected", d: "atomically, on chain" },
].map((step, i, arr) => (
{i + 1}
{step.s}
{step.d}
))}
);
}
function SecurityStats() {
return (
{[
{ v: "1", l: "Block to freeze a rogue agent" },
{ v: "100%", l: "Enforcement on chain" },
{ v: "0", l: "Off-chain trust deps" },
{ v: "5", l: "Guardrails in the validator" },
].map(s => (
{/* ── Left sidebar ── */}
{/* ── Main content ── */}
DOCS / {activeSection.title.toUpperCase()}
{activeSection.title}.
{activeSection.body}
{/* ── Right sidebar ── */}
);
}
function DocGroup({ title, children }) {
return (
{title}
{children}
);
}
function DocLink({ active, onClick, children }) {
return (
);
}
/* ── Shared prose helpers ─────────────────────────────────────────── */
function P({ children }) { return
{children}
; }
function H2({ children }) { return
{children}
; }
function Callout({ accent, title, children }) {
return (
{title}
{children}
);
}
function CodeSnippet({ lang, children }) {
return (
{lang}COPY
{children}
);
}
/* ── Section body components ──────────────────────────────────────── */
// Plain-language walkthrough for people using the dashboard directly —
// no code, no SDK, just what to click and why. The technical reference
// starts at Quickstart, below, for developers integrating the SDK.
function StartHereBody() {
const step = (n, title, body) => (
{n}
{title}
{body}
);
return (
<>
No installs, no code. This is the whole path from opening Beni to having a spending limit enforced on-chain.
1. Connect your wallet
{step("1", "Connect your wallet", "Click Open Beni, then connect any CIP-30 wallet — Eternl, Nami, Lace, Flint, Vespr, or Typhon. Your wallet never leaves your own device; Beni just reads your address and balance.")}
2. Set your limits & deploy
{step("2", "Set your limits", "In the dashboard, click New agent. Choose a per-transaction cap (the most a single spend can ever be) and a daily cap (the total allowed in any rolling 24 hours). Most people leave the owner field blank — that just means your own wallet is the one that can freeze or reclaim funds.")}
{step("3", "Review & pay", "You'll see exactly what you're about to sign before anything happens: your limits, and a one-time 2 ADA fee. Confirm, and your wallet will ask you to approve two transactions — the fee, then the deployment.")}
{step("4", "You're guarded", "From that point on, every spend through this wallet is checked against your limits by the Cardano ledger itself — not by Beni's servers, and not by trusting any app to behave.")}
3. Manage your agent
Once deployed, the sidebar's other tabs cover the rest: Live monitor for real-time activity, Transactions for full history, Approvals for anything above your cap waiting on your signature, and Rules & policies / Whitelist to change your limits later. The Emergency freeze button at the top halts all spending instantly if something looks wrong.
Message the Telegram bot instead — it walks through the same setup in two commands, right from your phone.
);
}
function QuickstartBody({ setActive }) {
return (
<>
Beni wraps any Cardano wallet provider with programmable spend rules. This guide installs the SDK and ships a guarded agent in under five minutes.
Node 18+, a Cardano wallet provider (Lucid Evolution, Mesh, or raw CIP-30), and an agent that constructs transactions on your behalf.
1. Install the SDK
{`npm install @lucid-evolution/lucid
# Copy sdk/ into your project and import from sdk/src/index.ts`}
Use agentSpend() exactly like a raw wallet send. If the transaction violates a rule, the Aiken validator rejects it on-chain and the SDK throws a typed error.
{`import { agentSpend } from "./sdk/src/index.js";
try {
const { txHash } = await agentSpend(lucid, wallet, recipientAddress, 50_000_000n);
console.log("Settled:", txHash);
} catch (e) {
// GuardrailViolationError — e.rule = "per_tx_cap" | "daily_cap" | "frozen" | "whitelist"
console.error(e.rule, e.message);
}`}Continue to Defining rules for the full policy surface, or jump to Approval flow for human-in-the-loop gating.
);
}
function InstallBody() {
return (
<>
Beni ships as a TypeScript SDK plus a set of audited Aiken contracts you deploy once per agent wallet.
Package install
{`npm install @lucid-evolution/lucid
pnpm add @lucid-evolution/lucid
bun add @lucid-evolution/lucid`}
Environment variables
{`# .env
BLOCKFROST_PREVIEW_KEY=preview...
AGENT_PRIVATE_KEY=ed25519_sk1...
OWNER_PKH=4b0f3ae1... # owner public key hash
ANTHROPIC_API_KEY=sk-ant-... # for AI assistant`}
Deploy the validator
One command compiles the Aiken contract and registers the thread token on Cardano:
{`npx tsx sdk/scripts/deploy-wallet.ts
# Writes beni-wallet-state.json with scriptAddress + threadTokenPolicyId`}Set BENI_SCRIPT_ADDRESS, BENI_THREAD_TOKEN_POLICY, and AGENT_ADDRESS as Vercel env vars, then redeploy.
);
}
function RulesBody() {
return (
<>
Rules are pure functions over a transaction's UTxO set. They compose — every rule must pass for the transaction to settle. Rules are encoded in the on-chain datum at deploy time.
Per-transaction cap
{`rule.perTxCap({ lovelace: 500_000_000n }) // ₳500 hard ceiling per tx`}
Rolling 24h cap
{`rule.dailyCap({ lovelace: 2_500_000_000n }) // ₳2,500 per 24h window`}
{`rule.requireApproval({ above: 250_000_000n }) // pause if > ₳250`}
Composing rules
Pass the full rules array to createAgentWallet(). All rules are evaluated on every Spend redeemer. Order does not matter — all must pass.
);
}
function ApprovalBody({ setActive }) {
return (
<>
When a rule emits requireApproval, the SDK queues the spend locally instead of broadcasting. The owner reviews and co-signs on-chain.
How it works
The approval queue is stored server-side (JSON file for local dev, Vercel KV in production). The dashboard polls for pending items and surfaces them under Approvals.
{`import { getPendingSpends, approveSpend, rejectSpend } from "./sdk/src/index.js";
const queue = await getPendingSpends(wallet);
// Approve — submits OwnerAction tx on-chain, bypasses all caps
const txHash = await approveSpend(lucid, wallet, queue[0].id);
// Or reject — no on-chain tx, marks item as rejected in queue
await rejectSpend(wallet, queue[0].id);`}The OwnerAction redeemer requires the owner PKH signature. Without it, the transaction is rejected — the approval queue cannot be faked.
);
}
function ContractsBody() {
return (
<>
All Beni validators are written in Aiken (v1.1.x, PlutusV3 / Conway era). Source and reproducible build artifacts are on GitHub.
Redeemers
{`pub type Redeemer {
Spend // agent-initiated spend — checks all caps + whitelist
OwnerAction // owner co-sign — bypasses caps, can update datum
FreezeWallet // sets is_frozen = true in continuing datum
}`}
Build from source
{`cd contracts
aiken build # outputs plutus.json with compiled validator CBOR
aiken check # run property tests
aiken docs # generate HTML docs`}Beni targets the Conway ledger era. lucid-cardano (legacy) cannot evaluate PlutusV3 cost models. Use @lucid-evolution/lucid v0.4.31+.
);
}
function ValidatorParamsBody() {
return (
<>
The Aiken validator is parameterized at deploy time. Parameters are baked into the compiled script — changing them produces a different script address and requires redeployment.
The 28-byte payment credential hash of the owner's signing key. Extracted with lucid.utils.getAddressDetails(ownerAddress).paymentCredential.hash. Stored in .env as OWNER_PKH.
thread_token_policy
The policy ID of the one-shot NFT minted at wallet creation. Used to identify the authoritative state UTxO. Generated automatically by deploy-wallet.ts.
Compilation
{`aiken build
# outputs: plutus.json → validator[0].compiledCode (CBOR hex)
# The SDK reads this CBOR and applies parameters via applyCborEncoding()`}Never share your AGENT_PRIVATE_KEY. The owner_pkh is public — it's a hash of the public key embedded in the script.
);
}
function ThreadTokensBody() {
return (
<>
A thread token is a one-shot NFT minted when the agent wallet is first deployed. It uniquely identifies and authenticates the authoritative state UTxO — making it impossible to forge a fake datum.
Purpose
Without a thread token, an attacker could create a UTxO at the script address with a forged datum (e.g., raising the per-tx cap). The validator checks for the thread token in every Spend — if absent, the transaction is rejected.
Minting
{`// The token is minted once, at deploy time.
// The seed UTxO is consumed — guaranteeing uniqueness.
const { threadTokenPolicyCbor, threadTokenPolicyId } =
await createAgentWallet(lucid, config);
// Returns: beni-wallet-state.json with both values`}
Fields are encoded in exactly this order as a Plutus Data Constr(0) using indefinite-length CBOR. The SDK's encodeDatum() handles this automatically — do not reorder fields.
Use GET /api/agent-state to inspect the live decoded datum in JSON form. The rawDatum field returns the raw CBOR hex for verification.
);
}
function BeniWrapBody() {
return (
<>
createAgentWallet(lucid, config) deploys a new guarded wallet on-chain. agentSpend() is the primary spend entry point — it validates, builds, and submits in one call.
createAgentWallet signature
{`async function createAgentWallet(
lucid: LucidEvolution,
config: CreateWalletConfig,
initialAda?: bigint, // default 5n (ADA to seed the script)
): Promise`}
per_tx_cap is a hard ceiling on any single agent-initiated transaction. It is stored in the on-chain datum and enforced by the Aiken validator — it cannot be bypassed off-chain.
Datum field
{`// In WalletDatum
per_tx_cap: Int // lovelace — max per single Spend transaction`}
Behavior
Before broadcasting, agentSpend() calls validateSpend() to pre-check the cap. If violated, it throws GuardrailViolationError with rule: "per_tx_cap" before hitting the chain. The on-chain validator performs the same check independently.
Example
{`// At deploy time — set the cap in the config:
perTxCapLovelace: 500_000_000n // ₳500 hard ceiling per transaction`}
Whitelist bypass
If the recipient's payment credential hash is in allowed_addresses, the per-tx cap check is skipped entirely. Useful for trusted counterparties like DEX contracts.
);
}
function RuleDailyCapBody() {
return (
<>
daily_cap enforces a rolling 24-hour spending budget. The window state is stored in the on-chain datum — no off-chain timer is required.
Datum fields
{`daily_cap: Int // lovelace — max per 24h window
last_window_start: Int // POSIX ms — start of current window
window_spent: Int // lovelace spent so far in window`}
Window reset
When now > last_window_start + 86_400_000, the validator treats the window as expired and allows spending up to the full cap again. The new last_window_start is written into the continuing output datum.
Example
{`// At deploy time:
dailyCapLovelace: 2_500_000_000n // ₳2,500 per rolling 24h window
// Query remaining budget:
import { getDailyUsage } from "./sdk/src/analytics.js";
const { windowSpentAda, dailyCapAda, pctUsed } = await getDailyUsage(lucid, wallet);`}
);
}
function RuleWhitelistBody() {
return (
<>
allowed_addresses registers trusted recipient addresses that bypass the per-tx cap check entirely. The daily cap still applies unless you freeze or raise it.
How it works
The validator extracts the payment credential hash from the recipient address in the transaction output. If that hash appears in allowed_addresses, the per-tx cap check is skipped for that transaction.
{`const hashToRemove = "4b0f3ae1...";
await ownerAction(lucid, wallet, {
...wallet.config,
allowedCredentialHashes: wallet.config.allowedCredentialHashes
.filter(h => h !== hashToRemove),
});`}Addresses change form across networks (mainnet vs testnet). Storing the 28-byte payment credential hash is network-agnostic and is how Cardano's ledger identifies addresses internally.
);
}
function RuleRequireApprovalBody() {
return (
<>
queueSpend() is the SDK function that implements the require-approval pattern — it stores the pending spend in a queue rather than broadcasting it immediately.
The owner co-signs using approveSpend(), which submits an OwnerAction redeemer. This satisfies the on-chain validator's owner-signature check and bypasses all caps.
{`import { rejectSpend } from "./sdk/src/index.js";
// No on-chain transaction — just marks the queue entry as rejected.
await rejectSpend(wallet, queue[0].id);`}The approval queue is backed by Vercel KV in production. Items persist across restarts and are visible across all dashboard sessions.
);
}
function McpServerBody() {
return (
<>
The Beni MCP server exposes guardrail tools directly to any MCP-compatible AI agent — including Claude Desktop. The agent calls check_limits or spend without ever touching Lucid, Aiken, or Blockfrost.
What is it
A lightweight Node.js process (sdk/mcp-server.ts) that implements the Model Context Protocol. Once connected, any MCP-capable agent gets five tools:
{[
{ name: "check_limits", desc: "Validate a proposed spend offline, instantly. No keys needed.", badge: "offline" },
{ name: "get_status", desc: "Current caps, daily usage, frozen state, window reset time.", badge: "offline" },
{ name: "spend", desc: "Submit a guarded spend to chain. Guardrails enforced on-chain.", badge: "on-chain" },
{ name: "freeze", desc: "Emergency freeze the wallet. Irreversible without ownerAction.", badge: "on-chain" },
{ name: "create_wallet",desc: "Deploy a new Beni wallet on Preview testnet.", badge: "on-chain" },
].map((t, i, arr) => (
{t.name}{t.desc}{t.badge}
))}
Setup
Install dependencies (one-time):
{`cd sdk && npm install`}
The server is ready. No build step — it runs directly with tsx.
Testing offline
The offline tools work with no keys and no deployed wallet. Run the server and call it from another terminal to verify:
{`# Start the server (it listens on stdin/stdout — this is just for manual testing)
npx tsx sdk/mcp-server.ts`}
Or run the guardrail demo (which exercises the same validation logic):
{`cd sdk && npx tsx examples/demo.ts
# Runs all 6 guardrail scenarios offline. No Blockfrost key required.`}
A ready-to-edit example with the correct path for this project is at sdk/claude-desktop-config.example.json.
Leave the env block empty and the offline tools (check_limits, get_status) still work. You can simulate guardrail decisions before you have a deployed wallet.
);
}
Object.assign(window, { SecurityPage, DocsPage });