IntentVM Developer Guide

IntentVM is Vexidus's declarative transaction engine. Instead of building low-level operations manually, developers describe what they want and the engine figures out the optimal execution path.

Quick Start

Using the Rust SDK

use vexidus_sdk::{IntentBuilder, parse_intent};
use vexidus_types::primitives::{Address, Amount, Timestamp};

// Option 1: Fluent builder
let (goal, constraints) = IntentBuilder::new()
    .stake(Amount::from_vxs(1000), None)
    .with_slippage(1)
    .build()
    .unwrap();

// Option 2: Natural language
let parsed = parse_intent("stake 1000 VXS").unwrap();

// Serialize for RPC submission
let json = IntentBuilder::new()
    .swap(Address::ZERO, usdc_addr, Amount::from_vxs(100))
    .to_json()
    .unwrap();

Using RPC Directly

# Submit an intent (natural language)
curl -s https://testnet.vexidus.io \
  -d '{"jsonrpc":"2.0","method":"vex_submitIntent","params":["swap 100 VXS for USDC","SENDER_ADDRESS"],"id":1}' | jq .

# Submit an intent (structured JSON)
curl -s https://testnet.vexidus.io \
  -d '{
    "jsonrpc":"2.0",
    "method":"vex_submitIntent",
    "params":["{\"goal\":{\"Stake\":{\"token\":\"0x0000000000000000000000000000000000000000000000000000000000000000\",\"amount\":1000000000000,\"validator\":null}},\"constraints\":{\"max_slippage\":1}}","SENDER_ADDRESS"],
    "id":1
  }' | jq .

# Preview execution plan before submitting
curl -s https://testnet.vexidus.io \
  -d '{"jsonrpc":"2.0","method":"vex_getExecutionPlan","params":["stake 1000 VXS"],"id":1}' | jq .

# Check intent status
curl -s https://testnet.vexidus.io \
  -d '{"jsonrpc":"2.0","method":"vex_getIntentStatus","params":["0xBUNDLE_HASH"],"id":1}' | jq .

Supported Intent Patterns

Natural Language (NL Parser)

Pattern	Example	Goal Type
Swap	`"swap 100 VXS for USDC"`	`Goal::Swap`
Swap with slippage	`"swap 50 ETH for VXS with 3% slippage"`	`Goal::Swap` + constraints
Stake	`"stake 1000 VXS"`	`Goal::Stake`
Stake with validator	`"stake 500 VXS with validator Vx1abc..."`	`Goal::Stake`
Bridge	`"bridge 10 SOL from solana"`	`Goal::Bridge`
Bridge + Swap	`"bridge 10 SOL from solana and swap to VXS"`	`Goal::Composite`
Register Name	`"register chris.vex"`	`Goal::Custom("register_vns:chris")`
Unknown	`"do something complex"`	`Goal::Custom` (future LLM)

Known Token Symbols

Symbol	Token	Mint Address
VXS	Native Vexidus	`Address::ZERO`
USDC	Bridged USDC	Blake3("ethereum_USDC")
USDT	Bridged USDT	Blake3("ethereum_USDT")
SOL	Bridged SOL	Blake3("solana_SOL")
ETH/WETH	Bridged ETH	Blake3("ethereum_ETH")
BTC/WBTC	Bridged BTC	Blake3("ethereum_WBTC")

Goal Types

pub enum Goal {
    Swap { from_token, to_token, amount },       // Token swap (requires VexiDEX)
    Stake { token, amount, validator },           // Stake VXS (works now)
    ProvideLiquidity { token_a, token_b, ... },   // LP provision (requires VexiDEX)
    Bridge { source_chain, token_symbol, amount, proof },  // Cross-chain bridge
    Composite(Vec<Goal>),                         // Atomic multi-step (1 intent, 1 sig, N ops)
    Custom(String),                               // NL-parsed (VNS, future LLM)
}

Current Execution Status

Goal	Status	Notes
Stake	Works end-to-end	Maps to native `Operation::Stake`
Swap	Routing stub	VexiDEX AMM is live (disc 38-41), but IntentVM `select_best_dex()` not yet wired to pool queries. Direct `vex_swap` works.
ProvideLiquidity	Routing stub	VexiDEX pools exist. IntentVM routing to pools pending. Direct `vex_addLiquidity` works.
Bridge	Works end-to-end	Tier-aware proof verification, bridgeability guards, composable with Swap/Stake
Composite	Works	Recursively processes sub-goals. "bridge + swap" = atomic
Custom	Partial	VNS registration works (`register_vns:name`). General LLM integration future.

Constraints

pub struct Constraints {
    pub max_slippage: Option<u8>,           // 0-100%
    pub deadline: Option<Timestamp>,        // Execution deadline
    pub min_output: Option<Amount>,         // Minimum output amount
    pub preferred_route: RoutePreference,   // Automatic, PreferDex, Custom
    pub sponsored_gas: bool,                // Gas sponsorship
}

RPC Methods

Method	Input	Output
`vex_submitIntent`	intent (JSON or NL string), sender address	Bundle hash
`vex_getExecutionPlan`	intent (JSON or NL string)	Execution steps, estimated gas, savings
`vex_getIntentStatus`	bundle hash	Status (pending/completed/failed), gas used

Architecture

User Input (NL or JSON)
    |
    v
NL Parser
    |  pattern matching, maps to Goal enum
    v
IntentBuilder
    |  fluent API, builds Goal + Constraints
    v
RPC: vex_submitIntent
    |  builds intent bundle, submits to mempool
    v
Execution Engine
    |  decomposes Goal -> native Operations
    |  Stake -> stake operation
    |  Swap -> DEX routing
    |  Composite -> recursive processing
    v
Block Execution

Future: LLM Integration

The NL parser currently uses regex patterns. For more complex intents, integrate an LLM:

User: "Buy VXS with half my USDC and stake it with the highest-APY validator"
  -> LLM extracts: Composite([
       Swap { from: USDC, to: VXS, amount: 50% of balance },
       Stake { token: VXS, amount: all, validator: highest_apy }
     ])

The Goal::Custom(String) variant is reserved for LLM-processed intents. Integration path:

Client sends NL to LLM API (Grok, Claude, etc.)
LLM returns structured Goal JSON
Client submits structured JSON via vex_submitIntent

IntentVM Architecture -- Deep dive into IntentVM design and provenance
Token Standards -- VexForge token operations that IntentVM composes
SDK Guide -- BundleBuilder and WalletClient for programmatic access

Quick Start​

Using the Rust SDK​

Using RPC Directly​

Supported Intent Patterns​

Natural Language (NL Parser)​

Known Token Symbols​

Goal Types​

Current Execution Status​

Constraints​

RPC Methods​

Architecture​

Future: LLM Integration​

Related Documentation​