VSC-71 Synthetic Asset Integration Guide

VSC-71 defines the IntentVM interface for tokenized stocks, commodities, indices, and perpetual contracts on the Vexidus blockchain. This guide is for licensees and developers who want to implement synthetic asset functionality on their Vexidus-based deployment.

info

VSC-71 is a licensee interface. The Goal types, NL parsing, and SDK stubs are provided by the protocol. Oracle pricing, margin engines, collateral vaults, and liquidation logic are your responsibility to implement and integrate.

Overview

VSC-71 adds three Goal types to IntentVM:

Goal	Purpose	Example Intent
MintSynthetic	Create tokenized representation of a real-world asset	"buy 10 AAPL with USDC"
OpenPosition	Open a leveraged perpetual contract	"open 5x long ETH perp with 100 USDC"
ClosePosition	Close an existing leveraged position	"close position Vx0abc..."

These goals are parsed and accepted by IntentVM's NL parser. When a user submits an intent like "buy 10 AAPL with USDC", IntentVM correctly identifies it as a synthetic mint (not a crypto swap) and structures it as a MintSynthetic goal with the appropriate symbol, amount, and collateral token.

What the Protocol Provides

1. Natural Language Parsing

The IntentVM NL parser distinguishes synthetic assets from cryptocurrency tokens:

Recognized stock symbols: AAPL, TSLA, GOOGL, AMZN, MSFT, NVDA, META, NFLX, AMD, INTC, and more

Recognized index/commodity symbols: SPY, QQQ, DIA, GOLD, SILVER, OIL

"buy 10 AAPL with USDC"          → MintSynthetic { symbol: "AAPL", amount: 10, collateral: USDC }
"buy 5 SPY with USDC"            → MintSynthetic { symbol: "SPY", amount: 5, collateral: USDC }
"open 5x long ETH perp with 100 USDC"  → OpenPosition { symbol: "ETH", direction: Long, leverage: 5, ... }
"short BTC 3x with 200 USDC"     → OpenPosition { symbol: "BTC", direction: Short, leverage: 3, ... }

2. Goal Type Definitions

MintSynthetic:
  - symbol: String (asset symbol, e.g. "AAPL", "GOLD")
  - amount: Amount (units to mint, scaled by synthetic's decimals)
  - collateral_token: Address (token used to back the synthetic)

OpenPosition:
  - symbol: String (underlying asset symbol)
  - direction: Long | Short
  - leverage: 1-100x
  - collateral: Amount
  - collateral_token: Address

ClosePosition:
  - position_id: Address (hash of the opening transaction)

3. SDK Stubs (IntentVM SDK)

The IntentVM SDK (available to all licensees) includes type definitions and parser support for VSC-71 goals. The SDK does not include execution logic -- it provides the interface for your implementation to plug into.

4. Constraint Support

All standard IntentVM constraints apply to VSC-71 goals:

Slippage -- Maximum acceptable price deviation from oracle
Deadline -- Execution must complete within time window
Max Fee -- Gas cost cap

What You Must Implement

1. Oracle Integration

VSC-71 requires a price oracle for:

Synthetic minting -- Fair value of the underlying asset (stocks, commodities, indices)
Perpetual contracts -- Mark price for PnL calculation, funding rates
Liquidation triggers -- Margin ratio monitoring

Requirements:

Oracle must provide signed price attestations (Ed25519 or ECDSA)
Price staleness check (reject prices older than your chosen threshold)
Multi-oracle aggregation recommended for manipulation resistance

Common oracle partners:

Chainlink (Cross-chain price feeds)
Pyth Network (High-frequency, Solana-native)
RedStone (Pull-based, gas efficient)
Band Protocol (Cross-chain IBC)
Custom API + attestation (for licensed data providers like Bloomberg, Refinitiv)

2. Collateral Vault

Synthetic minting requires over-collateralization:

User deposits 150 USDC collateral
Oracle reports AAPL = $195
Mint ratio: 150% (configurable)
User receives: floor(150 / 195 / 1.5) = 0.51 sAAPL

Your vault must handle:

Collateral deposits and withdrawals
Collateralization ratio enforcement (e.g. 150% minimum)
Liquidation when ratio drops below threshold
Collateral token whitelist (which tokens accepted as collateral)

3. Margin Engine (Perpetuals)

For OpenPosition and ClosePosition:

Initial margin -- Minimum collateral for leverage level
Maintenance margin -- Threshold for liquidation
Funding rates -- Periodic payments between longs and shorts
PnL settlement -- Mark-to-market on close
Maximum leverage -- Cap per asset class (e.g. 20x crypto, 5x stocks)

4. Liquidation System

Monitor collateralization ratios and margin levels
Trigger liquidation when thresholds are breached
Liquidation penalty distribution (protocol, liquidator, insurance fund)
Insurance fund for socialized losses

Integration Architecture

User: "buy 10 AAPL with USDC"
    |
    v
IntentVM NL Parser (provided)
    |  Parses → MintSynthetic { symbol: "AAPL", amount: 10, collateral: USDC }
    v
Your Execution Handler
    |  1. Query oracle for AAPL price
    |  2. Calculate required collateral (amount × price × collateral_ratio)
    |  3. Verify user has sufficient USDC
    |  4. Lock collateral in vault
    |  5. Mint sAAPL tokens to user
    v
On-Chain State Update
    |  Collateral locked, synthetic minted
    v
Event Emission
    |  SyntheticMinted { symbol, amount, collateral, price }

Hooking Into IntentVM Execution

When IntentVM encounters a MintSynthetic, OpenPosition, or ClosePosition goal, it delegates to the registered handler for VSC-71 operations. In the base protocol, this returns a "not yet active" response. Your implementation replaces this handler.

Integration points:

Register your VSC-71 execution handler with the state machine
Your handler receives the parsed Goal with all fields populated
Execute your oracle query, collateral logic, and minting/position management
Return success/failure events to IntentVM for atomic inclusion in the block

Recommended Token Structure

Synthetic Assets (sTokens)

Field	Value
Standard	VSC-7 (fungible token)
Symbol prefix	`s` (e.g. `sAAPL`, `sGOLD`, `sSPY`)
Decimals	8 (recommended for price precision)
Mintable	Yes (by vault contract only)
Burnable	Yes (on redemption)

Position NFTs (Optional)

For perpetual positions, consider using VSC-21 NFTs to represent open positions:

Field	Value
Standard	VSC-21 (NFT)
Metadata	Position details (entry price, leverage, direction, collateral)
Transferable	Optional (enables position trading)
Burnable	On close

Risk Considerations

Regulatory

Tokenized stocks may be classified as securities in your jurisdiction
Perpetual contracts face derivatives regulation
Consult legal counsel before deploying to mainnet
Implement KYC/AML gates as required by your jurisdiction

Technical

Oracle manipulation (flash loan attacks on reference prices)
Liquidation cascades during volatility
Funding rate manipulation
Stale price feeds during market closure (stocks)

Operational

Market hours -- Stock synthetics should respect trading hours or clearly disclose off-hours pricing
Corporate actions -- Stock splits, dividends require oracle updates and synthetic rebalancing
Circuit breakers -- Halt minting during extreme volatility

Example: Minimal MintSynthetic Handler

This pseudocode shows the minimum viable implementation:

fn handle_mint_synthetic(goal: MintSynthetic, sender: Address, state: &mut State) -> Result {
    // 1. Get oracle price
    let price = oracle.get_price(goal.symbol)?;
    ensure!(price.age_seconds < MAX_STALENESS, "Stale oracle price");

    // 2. Calculate required collateral
    let collateral_required = goal.amount * price.value * COLLATERAL_RATIO / PRECISION;

    // 3. Check and lock collateral
    let balance = state.get_balance(sender, goal.collateral_token);
    ensure!(balance >= collateral_required, "Insufficient collateral");
    state.lock_collateral(sender, goal.collateral_token, collateral_required)?;

    // 4. Mint synthetic token
    let synthetic_mint = state.get_or_create_synthetic(goal.symbol);
    state.mint(synthetic_mint, sender, goal.amount)?;

    // 5. Record position
    state.record_synthetic_position(sender, goal.symbol, goal.amount, collateral_required, price.value)?;

    Ok(Event::SyntheticMinted { symbol: goal.symbol, amount: goal.amount })
}

SDK Usage

The IntentVM SDK provides types for building VSC-71 intents programmatically:

// Using the IntentVM SDK (cross-chain adapter)
use intentvm_core::{IntentParser, Goal};

let parser = IntentParser::new(adapter);

// Parse NL → structured goal
let intent = parser.parse("buy 10 AAPL with USDC")?;
// intent.goal = Goal::MintSynthetic { symbol: "AAPL", amount: 10, collateral: USDC }

// Or build programmatically
let intent = IntentBuilder::new()
    .mint_synthetic("AAPL", 10, usdc_address)
    .with_slippage(1)
    .build()?;

VexFi Native Implementation

Vexidus's own synthetic asset platform (VexFi) will implement VSC-71 with a native oracle network and margin engine. VexFi is separate from the licensee interface -- it uses the same VSC-71 Goal types but with Vexidus-operated infrastructure.

The SDK stubs remain available to all licensees regardless of VexFi's status. Licensees are free to implement their own oracle integrations independently.

IntentVM Architecture -- Core IntentVM design
IntentVM Developer Guide -- NL patterns and RPC usage
Token Standards -- VSC-7 (fungible) and VSC-21 (NFT) standards used by synthetics
RPC Reference -- Full endpoint documentation

Overview​

What the Protocol Provides​

1. Natural Language Parsing​

2. Goal Type Definitions​

3. SDK Stubs (IntentVM SDK)​

4. Constraint Support​

What You Must Implement​

1. Oracle Integration​

2. Collateral Vault​

3. Margin Engine (Perpetuals)​

4. Liquidation System​

Integration Architecture​

Hooking Into IntentVM Execution​

Recommended Token Structure​

Synthetic Assets (sTokens)​

Position NFTs (Optional)​

Risk Considerations​

Regulatory​

Technical​

Operational​

Example: Minimal MintSynthetic Handler​

SDK Usage​

VexFi Native Implementation​

Related Documentation​