{
  "markdown": "# Spot — Limit, TWAP, Stop-Loss, Take-Profit Non-Custodial Decentralized DeFi Protocol\n\n**Agent-ready decentralized DeFi protocol for non-custodial advanced order types on EVM chains.**\n\nSpot provides non-custodial market, limit, TWAP, stop-loss, take-profit, and delayed-start orders on EVM chains, backed by immutable onchain contracts.\n\n**🔒 Security Audit Reports:** [Initial AstraSec audit](./Audit-AstraSec.pdf) and [updated AstraSec audit](./Audit2-AstraSec.pdf)\n\n## Why Spot\n\n1. ✅ **Non-custodial**: RePermit binds spend authorization to exact order hashes instead of handing custody to the protocol.\n2. 🔒 **Oracle-protected**: Trigger checks, slippage caps, freshness windows, and deadlines constrain execution.\n3. 🛡️ **Battle-tested**: Contracts are audited and covered by an extensive Foundry test suite.\n4. 🏗️ **Production-ready**: Spot is built for multi-chain deployment with repo-shipped config, ABIs, skill files, and a hosted MCP endpoint.\n\n## Supported Order Types\n\n1. Market swaps\n2. Limit orders\n3. TWAP orders\n4. Stop-loss orders\n5. Take-profit orders\n6. Delayed-start orders\n7. Chunked recurring execution\n\n## Supported Chains\n\nSpot supports multiple EVM chains. See [`config.json`](./config.json) as the canonical source for supported chains and runtime addresses.\n\nOrvex uses Spot's universal integration on Robinhood Chain (`4663`), with execution routing selected at fill time. No other Orvex mainnet deployment is listed in its [official contract directory](https://docs.orvex.fi/developer-resources/contract-addresses).\n\nRobinhood's solver adapters cover Kyber, Flytrade (`Magpie`), OpenOcean, and LI.FI (`LiFi`).\n\n## How It Works\n\nEach Spot order combines timing, sizing, trigger, and settlement rules in a single signed payload.\n\n1. `input.amount` is the per-fill chunk size.\n2. `input.maxAmount` is the total budget across fills.\n3. `output.limit` is the minimum acceptable output per chunk.\n4. `output.triggerLower` and `output.triggerUpper` define stop-loss and take-profit style trigger bands.\n5. `epoch` controls recurrence: `0` for one-shot, `> 0` for recurring fills.\n6. `start` and `deadline` define the execution window.\n\n`output.limit`, `triggerLower`, and `triggerUpper` are encoded as per-chunk output-token amounts in the output token's decimals.\n\nA typical order lifecycle is:\n\n1. **Order creation**: The user signs one EIP-712 order with chunk size, total amount, limits, slippage tolerance, epoch interval, and deadline.\n2. **Price attestation**: The cosigner signs both trigger-time and current market price data.\n3. **Execution trigger**: A whitelisted executor calls `Executor.execute()` when the order is eligible.\n4. **Validation**: `OrderReactor` validates signatures, checks `start`, enforces epoch windows, verifies timestamps, and applies slippage protection.\n5. **Settlement**: The reactor transfers input tokens, validates the fill result, and enforces minimum output.\n6. **Distribution**: Surplus output is distributed between the swapper and optional referrer according to configured shares.\n\n## Security\n\nSpot's contracts were professionally audited by AstraSec. See the **[initial security audit report](./Audit-AstraSec.pdf)** and **[updated security audit report](./Audit2-AstraSec.pdf)**.\nSpot is also oracle-protected: execution depends on cosigned trigger and market price data, freshness windows, and slippage checks.\n\n### Access Controls\n\n1. **WM Allowlist**: WM-gated entrypoints restrict privileged admin operations, and order execution honors exclusivity rules.\n2. **Two-Step Ownership**: `WM` uses OpenZeppelin `Ownable2Step` for secure ownership transfers.\n3. **Executor Binding**: Orders specify an authorized executor; only that executor can fill the order.\n4. **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.\n\n### Validation Layers\n\n1. **Order Validation**: `OrderValidationLib.validate()` checks all order fields for validity.\n2. **Signature Verification**: RePermit validates EIP-712 signatures and witness data binding.\n3. **Oracle Price Attestation**: The cosigner supplies trigger-time and current market price data used to gate execution.\n4. **Epoch Enforcement**: `EpochLib.update()` prevents early or duplicate fills within time windows.\n5. **Slippage Protection**: A maximum 50% slippage cap is enforced in `src/Constants.sol`.\n6. **Freshness Windows**: Current cosignatures expire after configurable time periods.\n7. **Trigger Timestamp Rules**: Trigger timestamps must be after `start` and no later than the current timestamp.\n\n### Economic Security\n\n1. **Witness-Bound Spending**: RePermit ties allowances to exact order hashes, preventing signature reuse.\n2. **Surplus Distribution**: Excess tokens are distributed between the swapper and referrer.\n3. **Exact Allowances**: `SafeERC20.forceApprove()` avoids allowance accumulation attacks.\n\n### Operational Security\n\n1. **Reentrancy Protection**: `OrderReactor` uses `ReentrancyGuard`; `Executor` and `Refinery` rely on WM gating and internal invariants.\n2. **Safe Token Handling**: The system supports USDT-like tokens and ETH handling semantics.\n3. **Emergency Pause**: `OrderReactor` can be paused by WM-allowed addresses.\n\n## Examples\n\nPlain-English examples:\n\n1. Sell a fixed amount once, but only if the execution meets a minimum output.\n2. Split a larger budget into equal chunks and execute one chunk every hour as a TWAP.\n3. Move into a safer asset if price falls below a stop-loss threshold, or exit on strength if a take-profit threshold is reached.\n\n### Single-Shot Limit Order\n\n```solidity\nOrder memory order = Order({\n    // ... standard fields\n    epoch: 0,                    // Single execution\n    input: Input({\n        amount: 1000e6,          // Exact amount to spend\n        maxAmount: 1000e6        // Same as amount\n    }),\n    output: Output({\n        limit: 950 ether,        // Minimum acceptable output\n        triggerLower: 0,         // No lower trigger gate\n        triggerUpper: 0          // No upper trigger gate\n    })\n});\n```\n\n### TWAP Order\n\n```solidity\nOrder memory order = Order({\n    // ... standard fields\n    epoch: 3600,                 // Execute every hour\n    input: Input({\n        amount: 100e6,           // 100 USDC per chunk\n        maxAmount: 1000e6        // 1000 USDC total budget\n    }),\n    output: Output({\n        limit: 95 ether,         // Minimum per chunk\n        triggerLower: 0,\n        triggerUpper: 0\n    })\n});\n```\n\n### Stop-Loss / Take-Profit Order\n\n```solidity\nOrder memory order = Order({\n    // ... standard fields\n    epoch: 0,                    // Single execution\n    start: block.timestamp,      // Order becomes active immediately\n    output: Output({\n        limit: 900 ether,        // Minimum per chunk output when executing\n        triggerLower: 950 ether, // Stop-loss boundary per chunk\n        triggerUpper: 1200 ether // Take-profit boundary per chunk\n    })\n});\n```\n\n## Technical Overview\n\n### Core Components\n\n1. 🧠 **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.\n2. ✍️ **RePermit** (`src/RePermit.sol`): Permit2-style EIP-712 signatures with witness data that bind allowances to exact order hashes, preventing signature reuse.\n3. 🧾 **Cosigner** (`src/ops/Cosigner.sol`): Attests to trigger-time and current market prices with token validation.\n4. 🛠️ **Executor** (`src/Executor.sol`): Whitelisted fillers that execute eligible orders, enforce minimum output, and distribute surplus.\n5. 🔐 **WM** (`src/ops/WM.sol`): Two-step ownership allowlist manager for executors and admin functions with event emission.\n6. 🏭 **Refinery** (`src/ops/Refinery.sol`): Operations utility for batching multicalls and sweeping token balances by basis points.\n\n### Order Structure\n\nBased on `src/Structs.sol`, each order contains:\n\n```solidity\nstruct Order {\n    address reactor;           // OrderReactor contract address\n    address executor;          // Authorized executor for this order\n    Exchange exchange;         // Exchange parameters, referrer, and data\n    address swapper;           // Order creator/signer\n    uint256 nonce;             // Unique identifier\n    uint256 start;             // Earliest execution timestamp\n    uint256 deadline;          // Expiration timestamp\n    uint256 chainid;           // Chain ID for cross-chain validation\n    uint32 exclusivity;        // BPS-bounded exclusive execution\n    uint32 epoch;              // Seconds between fills (0 = single-use)\n    uint32 slippage;           // BPS applied to cosigned price\n    uint32 freshness;          // Cosignature validity window in seconds\n    Input input;               // Token to spend\n    Output output;             // Token to receive\n}\n\nstruct Input {\n    address token;             // Input token address\n    uint256 amount;            // Per-fill chunk amount\n    uint256 maxAmount;         // Total amount across all fills\n}\n\nstruct Output {\n    address token;             // Output token address\n    uint256 limit;             // Minimum acceptable output, in output-token decimals, per chunk\n    uint256 triggerLower;      // Lower trigger boundary, in output-token decimals, per chunk\n    uint256 triggerUpper;      // Upper trigger boundary, in output-token decimals, per chunk\n    address recipient;         // Where to send output tokens\n}\n```\n\n### Limits & Constants\n\n1. **Maximum Slippage**: Up to 5,000 BPS, or 50%, inclusive, defined in `src/Constants.sol`.\n2. **Basis Points**: 10,000 BPS equals 100%.\n3. **Freshness Requirements**: Must be greater than 0 seconds and less than epoch duration when `epoch != 0`.\n4. **Epoch Behavior**: `0` means single execution; values above `0` mean recurring execution with that interval.\n5. **Gas Optimization**: Foundry optimizer runs are set to `1,000,000`.\n\n### Multi-Chain Deployment\n\nThe protocol is designed for deployment across EVM-compatible chains with deterministic addresses via CREATE2. Configuration is managed through [`config.json`](./config.json).\n\n## For Integrators\n\nThis repository ships these integration surfaces:\n\n1. Root package `@orbs-network/spot` for config, build orchestration, contracts, and published metadata inputs.\n2. Self-contained skill package [`skill/`](./skill/) published as `@orbs-network/spot-skill`.\n3. Skills-only OpenAI plugin artifact generated with `npm run plugin:build` for marketplace testing and submission.\n4. Hosted MCP endpoint at [`https://agents-sink.orbs.network/mcp`](https://agents-sink.orbs.network/mcp).\n5. Hosted raw files at [`https://orbs-network.github.io/spot/`](https://orbs-network.github.io/spot/) for direct bundle consumption.\n6. Hosted skill distribution on [Clawhub](https://clawhub.ai/eranp-orbs/spot-advanced-swap-orders) for direct skill discovery.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run fmt\n```\n\nNotes:\n\n1. `npm run build` runs `npm run sync` and then `forge build --extra-output-files abi`.\n2. `npm run plugin:build` generates the untracked plugin bundle at `dist/spot/`.\n3. Use `forge test` for the Foundry suite.\n\n## Contributing\n\n1. Make the smallest coherent change.\n2. Keep `skill/`, hosted MCP references, and any affected published surfaces in sync.\n3. Run `npm run build` after changes.\n4. Run tests when behavior changes or when explicitly requested.\n\n## Operational Notes\n\n1. **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.\n2. **Input Tokens**: Orders spend ERC-20 tokens; wrap native ETH before creating orders.\n\n## Support\n\n1. **Issues**: Use GitHub Issues for bug reports and feature requests.\n2. **Documentation**: The repo includes inline code documentation and the canonical skill references.\n\n## License\n\nMIT. See [`LICENSE`](./LICENSE).\n",
  "bytes": 12105,
  "sha": "762dc95f0cbf22ec3a0ad0440c83ca40671798c38548bb9788b9b900983cb5c3",
  "repo_slug": "orbs-network/spot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_orbs_network_spot_1a1c43b0/readme"
}