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 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)
• Slashing by the config authority: A proven violation slashes the bond and victims are compensated. On-chain violation proofs and dispute windows are on the roadmap.
• Trust scores: On-chain reputation that counterparties can verify before transacting

The reference program is live on devnet, and the product surfaces are public: the Trust Explorer, the read-only trust API at /api/trust, the launch page, and the Panta markets feed at /api/markets.

Quick Start

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

1. Connect Your Wallet

Visit equxi.tech/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
// A proven violation is slashable by the config authority

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 (closes account)
     ↓
  execute_slash → escrow vault → compensate_victim → victim

Rules (Constraints)

Rules define what an agent is allowed to do. They are stored on-chain and are the criteria a slash is judged against. An agent may hold many rules.

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 configured authority executes a slash:

1. Detection: An off-chain monitor detects a violation (operators may also self-report)
2. execute_slash: The authority calls this instruction with the agent, bond and vault accounts
3. Escrow: The slashed lamports move from the bond into the program-owned vault PDA. They are never sent to the admin.
4. compensate_victim: The victim is paid out of the vault. This does not modify the bond's recorded amount.
5. Trust score: The agent's trust score is reduced

Slashing is non-custodial: the admin can trigger a seizure but can never receive the funds. A payout can never exceed its slash amount, a slash can only be compensated once, and payouts are bounded by the vault balance.

The config authority is the program's upgrade authority. initialize takes no admin argument and verifies the signer against the program's ProgramData account, so the config can never be initialized with a stranger as admin.

Slashing today is authority-signed. On-chain violation proofs, dispute windows and decentralized slashing are the next roadmap items in SPEC.md.

Program Instructions

The Equxi program exposes 11 instructions, and the devnet deployment runs all 11: the escrow vault, the agent migration, the unbonding window and top_up_bond were each deployed in place and byte-verified against the CI build.

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.