@orbs-network/spot-mcp 2.4.0 → 2.4.1

package/README.md

@@ -0,0 +1,252 @@
+<!-- Generated by script/sync.mjs from the repository root README.md. Do not edit directly. -->
+
+> Auto-synced workspace README for `@orbs-network/spot-mcp`. Repo-relative links are rewritten to canonical GitHub URLs.
+# 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](https://github.com/orbs-network/spot/blob/master/Audit-AstraSec.pdf)** 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`](https://github.com/orbs-network/spot/blob/master/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](https://github.com/orbs-network/spot/blob/master/Audit-AstraSec.pdf)**.
+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
+
+```solidity
+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
+
+```solidity
+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
+
+```solidity
+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:
+
+```solidity
+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`](https://github.com/orbs-network/spot/blob/master/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/`](https://github.com/orbs-network/spot/tree/master/skill) published as `@orbs-network/spot-skill`.
+3. MCP package [`mcp/`](https://github.com/orbs-network/spot/tree/master/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/`](https://orbs-network.github.io/spot/) for direct bundle consumption.
+
+## Development
+
+```bash
+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`](https://github.com/orbs-network/spot/blob/master/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@orbs-network/spot-mcp",
-    "version": "2.4.0",
+    "version": "2.4.1",
     "mcpName": "io.github.orbs-network/spot",
     "description": "MCP adapter for Spot Advanced Swap Orders.",
     "homepage": "https://orbs-network.github.io/spot/",
@@ -21,11 +21,13 @@
         "spot-mcp": "./stdio.mjs"
     },
     "files": [
-        "stdio.mjs"
+        "*.json",
+        "*.md",
+        "*.mjs"
     ],
     "dependencies": {
         "@modelcontextprotocol/sdk": "1.27.1",
         "zod": "4.3.6",
-        "@orbs-network/spot-skill": "2.4.0"
+        "@orbs-network/spot-skill": "2.4.1"
     }
 }

package/server.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+    "name": "io.github.orbs-network/spot",
+    "title": "Spot Advanced Swap Orders",
+    "description": "Use for gasless non-custodial EVM market, limit, TWAP, stop-loss, take-profit, delayed-start orders.",
+    "repository": {
+        "url": "https://github.com/orbs-network/spot",
+        "source": "github"
+    },
+    "version": "2.4.1",
+    "packages": [
+        {
+            "registryType": "npm",
+            "identifier": "@orbs-network/spot-mcp",
+            "version": "2.4.1",
+            "transport": {
+                "type": "stdio"
+            }
+        }
+    ]
+}