Equxi Documentation

On-chain accountability infrastructure for autonomous AI agents on Solana.

Overview

Equxi is a Solana program that solves a fundamental problem in AI agent commerce: nobody can trust an autonomous agent with real capital or financial obligations.

Traditional wallets only hold funds. They cannot enforce on-chain behavioral constraints, nor automatically seize an operator's collateral to compensate victims when an agent misbehaves. Equxi fixes this by providing:

• Operator bonding: Agents must lock SOL as collateral before operating
• Behavioral constraints: On-chain rules that limit what an agent can do (spend limits, program allowlists, timelocks)
• Automatic slashing: When rules are violated, the bond is slashed and victims are compensated
• Trust scores: On-chain reputation that counterparties can verify before transacting

Quick Start

Get a working agent with bond and rules in under 5 minutes.

1. Connect Your Wallet

Visit equxi.sithunyein.com/app.html and connect your Phantom wallet. Make sure you're on Devnet.

2. Register an Agent

Click + Register in the Agents tab. Give your agent a name and select its type (Trader, Assistant, Framework, or Custom). This creates an on-chain account at a PDA derived from the program.

3. Lock a Bond

Click + Lock Funds in the Bonds tab. Deposit SOL as collateral. This bond is your agent's accountability guarantee: if it misbehaves, victims are compensated from it.

4. Add Rules

Click + Add Rule in the Rules tab. Set constraints on your agent's behavior:

• Spend Limit: Maximum SOL per time period
• Program Allowlist: Only interact with approved programs
• Timelock: Delay large transactions for review

// Your agent is now live on Solana devnet
// Constraints are enforced on-chain
// If violated, slashing happens automatically

SDK Installation

For programmatic access to Equxi from TypeScript or JavaScript:

npm install @equxi/sdk @solana/web3.js @coral-xyz/anchor

Or clone the repository and build from source:

git clone https://github.com/thesithunyein/equxi.git
cd equxi/sdk
npm install
npm run build

import { EquxiClient } from "@equxi/sdk";
import { Connection, PublicKey } from "@solana/web3.js";
import { AnchorProvider } from "@coral-xyz/anchor";

// Initialize
const connection = new Connection("https://api.devnet.solana.com");
const provider = new AnchorProvider(wallet, connection, { commitment: "confirmed" });
const client = new EquxiClient(provider);

// Register an agent
const { agentPDA } = await client.registerAgent("AlphaTrader", { trader: {} });

// Lock a bond (5 SOL, 30-day lock period)
await client.createBond(agentPDA, 5_000_000_000, 2_592_000);

// Add a spend limit (1 SOL per day)
await client.addConstraint(agentPDA, { spendLimit: {} }, {
  maxAmount: 1_000_000_000,
  maxPerPeriod: 5_000_000_000,
  periodSeconds: 86400,
});

// Query on-chain state
const agent = await client.getAgent(agentPDA);
console.log("Trust score:", agent.trustScore);

Agents

An agent is an AI program that acts on behalf of an operator. Each agent has:

• Operator: The wallet that registered the agent (controls it)
• Agent Type: Trader, Assistant, Framework, or Custom
• Trust Score: 0–100 reputation score (starts at 50)
• Status: Active, Suspended, or Slashed
• Registered At: Unix timestamp of registration

Agent accounts are stored at Program Derived Addresses (PDAs) using the operator's wallet and a nonce as seeds. This means each operator can have multiple agents with unique addresses.

Bonds

A bond is SOL locked by the operator as collateral. It serves as the agent's financial guarantee.

How Bonds Work

• Operator deposits SOL when creating a bond
• Bond has a lock period (e.g., 30 days): cannot be withdrawn early
• After the lock period, the operator can withdraw via withdraw_bond
• If the agent violates rules, the bond is slashed (partially or fully)
• Slashed funds are sent to the victim via compensate_victim

Bond Lifecycle

create_bond → [active] → [lock expires] → withdraw_bond
     ↓                      ↓
  slashed by admin    operator reclaims funds

Rules (Constraints)

Rules define what an agent is allowed to do. They are enforced on-chain: violations trigger automatic slashing.

Constraint Types

// Example: Agent can spend max 1 SOL per day
{
  constraintType: { spendLimit: {} },
  maxAmount: 1_000_000_000,       // 1 SOL in lamports
  maxPerPeriod: 5_000_000_000,    // 5 SOL total budget
  periodSeconds: 86400             // 24 hours
}

Slashing

When an agent violates its constraints, the program admin (config authority) can execute a slash:

1. Detection: Off-chain monitor detects violation (or operator self-reports)
2. execute_slash: Admin calls this instruction with the agent and bond accounts
3. Bond reduction: The slashed amount is deducted from the bond
4. compensate_victim: Slashed funds are transferred to the victim's wallet
5. Trust score update: Agent's trust score is decreased via update_trust_score

The config authority (admin) is set during initialize and can only be changed by the current authority. This prevents unauthorized slashing.

Program Instructions

The Equxi program exposes 8 instructions:

Account Layout

Key on-chain accounts and their structures:

Config (Singleton)

{
  authority: PublicKey,    // Admin who can slash/compensate
  bump: u8,               // PDA bump seed
  nonce: u64,             // Global nonce counter
}

Agent (PDA)

{
  operator: PublicKey,     // Wallet that registered this agent
  name: [u8; 32],         // Agent name (fixed-size)
  agentType: AgentType,   // Trader | Assistant | Framework | Custom
  trustScore: u16,        // 0-100 reputation
  status: AgentStatus,    // Active | Suspended | Slashed
  registeredAt: i64,      // Unix timestamp
  bump: u8,               // PDA bump seed
}

Bond (PDA)

{
  agent: PublicKey,        // Associated agent PDA
  operator: PublicKey,     // Bond owner
  amount: u64,            // Locked amount in lamports
  lockExpiry: i64,        // Unix timestamp when withdrawal allowed
  createdAt: i64,
  bump: u8,
}

Constraint (PDA)

{
  agent: PublicKey,        // Associated agent PDA
  constraintType: ConstraintType,
  maxAmount: u64,
  maxPerPeriod: u64,
  periodSeconds: u32,
  active: bool,
  bump: u8,
}

SDK Reference

The TypeScript SDK provides typed wrappers for all program instructions.

EquxiClient Methods

// Full example: register, bond, constrain, query
import { EquxiClient } from "@equxi/sdk";
import { PublicKey } from "@solana/web3.js";

const client = new EquxiClient(provider);

// 1. Register
const { agentPDA } = await client.registerAgent("MyBot", { trader: {} });

// 2. Bond (10 SOL, 60-day lock)
const { bondPDA } = await client.createBond(
  agentPDA,
  10 * 1_000_000_000,  // 10 SOL
  60 * 24 * 60 * 60     // 60 days
);

// 3. Constrain (spending limit)
await client.addConstraint(agentPDA, { spendLimit: {} }, {
  maxAmount: 2_000_000_000,     // 2 SOL max single tx
  maxPerPeriod: 20_000_000_000, // 20 SOL per day
  periodSeconds: 86400,
});

// 4. Query
const agent = await client.getAgent(agentPDA);
console.log(`Agent: ${agent.name}, Trust: ${agent.trustScore}`);
const constraints = await client.getAgentConstraints(agentPDA);
console.log(`${constraints.length} active rules`);

Program IDL

The Interface Definition Language (IDL) describes the program's types and instructions. The full IDL is in target/idl/equxi.json after building.

{
  "version": "0.1.0",
  "name": "equxi",
  "instructions": [
    { "name": "initialize", "accounts": [...], "args": [] },
    { "name": "registerAgent", "accounts": [...], "args": [...] },
    { "name": "createBond", "accounts": [...], "args": [...] },
    { "name": "withdrawBond", "accounts": [...], "args": [...] },
    { "name": "addConstraint", "accounts": [...], "args": [...] },
    { "name": "executeSlash", "accounts": [...], "args": [...] },
    { "name": "compensateVictim", "accounts": [...], "args": [...] },
    { "name": "updateTrustScore", "accounts": [...], "args": [...] }
  ],
  "types": [
    "AgentType", "AgentStatus", "ConstraintType", "Config", "Agent", "Bond", "Constraint"
  ]
}

Deployment

Equxi is deployed on Solana Devnet. To deploy your own instance:

# Clone and build
git clone https://github.com/thesithunyein/equxi.git
cd equxi
chmod +x setup.sh
./setup.sh

The setup script will:

1. Check prerequisites (Rust, Solana CLI, Anchor)
2. Configure Solana for devnet
3. Generate a program keypair
4. Build the program with cargo build-sbf
5. Deploy to devnet
6. Print the program ID and Explorer link

FAQ

Why do agents need bonds?

Without bonds, there's no financial consequence for misbehavior. Counterparties won't transact with agents that can lose their money with no recourse. Bonds create skin-in-the-game.

Who decides when to slash?

The config authority (set during initialize) can execute slashes. In production, this could be a DAO, a multisig, or an oracle network that monitors on-chain behavior.

Can an operator withdraw their bond anytime?

No. Bonds have a lock period. The operator specifies this when creating the bond (e.g., 30 days). Early withdrawal is not possible: this prevents operators from bonding, misbehaving, and withdrawing before consequences.

What happens if an agent is slashed below minimum?

The agent's status changes to Slashed. The operator would need to create a new bond to continue operating. The trust score is reduced, signaling to counterparties that this agent has a history of violations.

Is this on mainnet?

Currently deployed on Devnet for testing and grant verification. Mainnet deployment would require a security audit and sufficient TVL in the bonding mechanism.