Spot MCP Server

Spot — Limit, TWAP, Stop-Loss, Take-Profit Non-Custodial Decentralized DeFi Protocol

Agent-ready decentralized DeFi protocol for non-custodial advanced order types on EVM chains.

Spot provides non-custodial market, limit, TWAP, stop-loss, take-profit, and delayed-start orders on EVM chains, backed by immutable onchain contracts.

🔒 Security Audit Report by AstraSec

Why Spot

1. ✅ Non-custodial: RePermit binds spend authorization to exact order hashes instead of handing custody to the protocol.
2. 🔒 Oracle-protected: Trigger checks, slippage caps, freshness windows, and deadlines constrain execution.
3. 🛡️ Battle-tested: Contracts are audited and covered by an extensive Foundry test suite.
4. 🏗️ Production-ready: Spot is built for multi-chain deployment with repo-shipped config, ABIs, skill files, and MCP metadata.

Supported Order Types

1. Market swaps
2. Limit orders
3. TWAP orders
4. Stop-loss orders
5. Take-profit orders
6. Delayed-start orders
7. Chunked recurring execution

Supported Chains

Spot supports multiple EVM chains. See config.json as the canonical source for supported chains and runtime addresses.

How It Works

Each Spot order combines timing, sizing, trigger, and settlement rules in a single signed payload.

1. input.amount is the per-fill chunk size.
2. input.maxAmount is the total budget across fills.
3. output.limit is the minimum acceptable output per chunk.
4. output.triggerLower and output.triggerUpper define stop-loss and take-profit style trigger bands.
5. epoch controls recurrence: 0 for one-shot, > 0 for recurring fills.
6. start and deadline define the execution window.

output.limit, triggerLower, and triggerUpper are encoded as per-chunk output-token amounts in the output token's decimals.

A typical order lifecycle is:

1. Order creation: The user signs one EIP-712 order with chunk size, total amount, limits, slippage tolerance, epoch interval, and deadline.
2. Price attestation: The cosigner signs both trigger-time and current market price data.
3. Execution trigger: A whitelisted executor calls Executor.execute() when the order is eligible.
4. Validation: OrderReactor validates signatures, checks start, enforces epoch windows, verifies timestamps, and applies slippage protection.
5. Settlement: The reactor transfers input tokens, the executor runs adapter logic via delegatecall, and the system enforces minimum output.
6. Distribution: Surplus output is distributed between the swapper and optional referrer according to configured shares.

Security

Spot's contracts were professionally audited. See the Security Audit Report. Spot is also oracle-protected: execution depends on cosigned trigger and market price data, freshness windows, and slippage checks.

Access Controls

1. WM Allowlist: WM-gated entrypoints restrict privileged admin operations, and order execution honors exclusivity rules.
2. Two-Step Ownership: WM uses OpenZeppelin Ownable2Step for secure ownership transfers.
3. Executor Binding: Orders specify an authorized executor; only that executor can fill the order.
4. Non-Exclusive Fillers: exclusivity = 0 locks fills to the designated executor, while values above zero allow third-party fillers that satisfy the higher minimum output requirement.

Validation Layers

1. Order Validation: OrderValidationLib.validate() checks all order fields for validity.
2. Signature Verification: RePermit validates EIP-712 signatures and witness data binding.
3. Oracle Price Attestation: The cosigner supplies trigger-time and current market price data used to gate execution.
4. Epoch Enforcement: EpochLib.update() prevents early or duplicate fills within time windows.
5. Slippage Protection: A maximum 50% slippage cap is enforced in src/Constants.sol.
6. Freshness Windows: Current cosignatures expire after configurable time periods.
7. Trigger Timestamp Rules: Trigger timestamps must be after start and no later than the current timestamp.

Economic Security

1. Witness-Bound Spending: RePermit ties allowances to exact order hashes, preventing signature reuse.
2. Surplus Distribution: Excess tokens are distributed between the swapper and referrer.
3. Exact Allowances: SafeERC20.forceApprove() avoids allowance accumulation attacks.

Operational Security

1. Reentrancy Protection: OrderReactor uses ReentrancyGuard; Executor and Refinery rely on WM gating and internal invariants.
2. Safe Token Handling: The system supports USDT-like tokens and ETH handling semantics.
3. Delegatecall Isolation: Adapters run in the controlled executor context with validation around settlement.
4. Emergency Pause: OrderReactor can be paused by WM-allowed addresses.

Examples

Plain-English examples:

1. Sell a fixed amount once, but only if the execution meets a minimum output.
2. Split a larger budget into equal chunks and execute one chunk every hour as a TWAP.
3. Move into a safer asset if price falls below a stop-loss threshold, or exit on strength if a take-profit threshold is reached.

Single-Shot Limit Order

Order memory order = Order({
    // ... standard fields
    epoch: 0,                    // Single execution
    input: Input({
        amount: 1000e6,          // Exact amount to spend
        maxAmount: 1000e6        // Same as amount
    }),
    output: Output({
        limit: 950 ether,        // Minimum acceptable output
        triggerLower: 0,         // No lower trigger gate
        triggerUpper: 0          // No upper trigger gate
    })
});

TWAP Order

Order memory order = Order({
    // ... standard fields
    epoch: 3600,                 // Execute every hour
    input: Input({
        amount: 100e6,           // 100 USDC per chunk
        maxAmount: 1000e6        // 1000 USDC total budget
    }),
    output: Output({
        limit: 95 ether,         // Minimum per chunk
        triggerLower: 0,
        triggerUpper: 0
    })
});

Stop-Loss / Take-Profit Order

Order memory order = Order({
    // ... standard fields
    epoch: 0,                    // Single execution
    start: block.timestamp,      // Order becomes active immediately
    output: Output({
        limit: 900 ether,        // Minimum per chunk output when executing
        triggerLower: 950 ether, // Stop-loss boundary per chunk
        triggerUpper: 1200 ether // Take-profit boundary per chunk
    })
});

Technical Overview

Core Components

1. 🧠 OrderReactor (src/OrderReactor.sol): Validates orders, checks epoch constraints, computes minimum output from cosigned prices, settles via inlined implementation with reentrancy protection, and supports emergency pause via the WM allowlist.
2. ✍️ RePermit (src/RePermit.sol): Permit2-style EIP-712 signatures with witness data that bind allowances to exact order hashes, preventing signature reuse.
3. 🧾 Cosigner (src/ops/Cosigner.sol): Attests to trigger-time and current market prices with token validation.
4. 🛠️ Executor (src/Executor.sol): Whitelisted fillers that run venue logic via delegatecall to adapters, enforce minimum output, and distribute surplus.
5. 🔐 WM (src/ops/WM.sol): Two-step ownership allowlist manager for executors and admin functions with event emission.
6. 🏭 Refinery (src/ops/Refinery.sol): Operations utility for batching multicalls and sweeping token balances by basis points.

Order Structure

Based on src/Structs.sol, each order contains:

struct Order {
    address reactor;           // OrderReactor contract address
    address executor;          // Authorized executor for this order
    Exchange exchange;         // Adapter, referrer, and data
    address swapper;           // Order creator/signer
    uint256 nonce;             // Unique identifier
    uint256 start;             // Earliest execution timestamp
    uint256 deadline;          // Expiration timestamp
    uint256 chainid;           // Chain ID for cross-chain validation
    uint32 exclusivity;        // BPS-bounded exclusive execution
    uint32 epoch;              // Seconds between fills (0 = single-use)
    uint32 slippage;           // BPS applied to cosigned price
    uint32 freshness;          // Cosignature validity window in seconds
    Input input;               // Token to spend
    Output output;             // Token to receive
}

struct Input {
    address token;             // Input token address
    uint256 amount;            // Per-fill chunk amount
    uint256 maxAmount;         // Total amount across all fills
}

struct Output {
    address token;             // Output token address
    uint256 limit;             // Minimum acceptable output, in output-token decimals, per chunk
    uint256 triggerLower;      // Lower trigger boundary, in output-token decimals, per chunk
    uint256 triggerUpper;      // Upper trigger boundary, in output-token decimals, per chunk
    address recipient;         // Where to send output tokens
}

Limits & Constants

1. Maximum Slippage: Up to 5,000 BPS, or 50%, inclusive, defined in src/Constants.sol.
2. Basis Points: 10,000 BPS equals 100%.
3. Freshness Requirements: Must be greater than 0 seconds and less than epoch duration when epoch != 0.
4. Epoch Behavior: 0 means single execution; values above 0 mean recurring execution with that interval.
5. Gas Optimization: Foundry optimizer runs are set to 1,000,000.

Multi-Chain Deployment

The protocol is designed for deployment across EVM-compatible chains with deterministic addresses via CREATE2. Configuration is managed through config.json.

For Integrators

This repository ships these integration surfaces:

1. Root package @orbs-network/spot for config, build orchestration, contracts, and published metadata inputs.
2. Self-contained skill package skill/ published as @orbs-network/spot-skill.
3. MCP package mcp/ published as @orbs-network/spot-mcp with server name io.github.orbs-network/spot.
4. Hosted raw files at https://orbs-network.github.io/spot/ for direct bundle consumption.
5. Hosted skill distribution on Clawhub for direct skill discovery.

Development

npm install
npm run build
npm test
npm run fmt

Notes:

1. npm run build runs npm run sync and then forge build --extra-output-files abi.
2. Sync-generated skill metadata, MCP registry metadata, and derived mcp/package.json fields should not be hand-maintained; MCP-owned fields there such as pinned runtime dependencies are maintained in mcp/package.json.
3. Use forge test for the Foundry suite.

Contributing

1. Make the smallest coherent change.
2. Keep skill/, MCP metadata, and any affected published surfaces in sync.
3. Run npm run build after changes.
4. Run tests when behavior changes or when explicitly requested.

Operational Notes

1. Executor ETH Refunds: Order execution returns the reactor's ETH balance to the filler. Keep executors funded, and treat unexpected reactor ETH as recoverable by WM-allowed addresses.
2. Input Tokens: Orders spend ERC-20 tokens; wrap native ETH before creating orders.

Support

1. Issues: Use GitHub Issues for bug reports and feature requests.
2. Documentation: The repo includes inline code documentation and the canonical skill references.

License

MIT. See LICENSE.