mantle-openclaw-competition

name	mantle-openclaw-competition
version	0.1.18
description	Use for ANY on-chain DeFi operation on the Mantle network by OpenClaw in the asset accumulation competition — swapping, liquidity provision, Aave V3 lending, ERC-20 approvals, MNT wrap/unwrap, or portfolio/state reads. TRIGGER when the user: (a) mentions OpenClaw, mantle-cli, or the Mantle asset accumulation competition; (b) asks to swap / trade / exchange tokens on Mantle via Agni, Fluxion, or Merchant Moe; (c) asks to add / remove / manage liquidity (LP) on whitelisted Mantle pools, including xStocks pairs; (d) asks to supply / deposit / lend / borrow / repay / withdraw / set-collateral on Aave V3 on Mantle; (e) asks to wrap MNT → WMNT or unwrap WMNT → MNT; (f) asks to approve an ERC-20 spender; (g) wants to discover whitelisted assets, pools, pairs, routers, fee tiers, or bin steps; (h) wants to query balances, allowances, transaction status, or Aave positions on Mantle; (i) wants to optimize portfolio USD value via yield, leverage, or exit timing. SKIP for: operations on other chains (Ethereum, Base, Arbitrum, BSC), Mantle infra / smart-contract development, or anything outside whitelisted protocols. Enforces hard rules: CLI-only execution via `mantle-cli … --json` (NEVER the mantle-mcp MCP server), STOP-on-error (no auto-retry; recommend restart), quote-before-swap, sign-and-WAIT per tx, and absolute refusal of native/ERC-20 token transfers or fabricated calldata (no Python / JS / raw RPC / utils encoding).

OpenClaw Competition — DeFi Operations Guide

Overview

OpenClaw competes in the Mantle asset accumulation competition: each participant starts with 100 MNT in a fresh wallet and grows total portfolio value (USD) through whitelisted protocol interactions. This skill provides the workflow skeleton; details for each operation live in references/.

Setup

# Install mantle-cli (CLI only — no MCP server)
npm install @mantleio/mantle-cli
npx mantle-cli --help   # verify

If this skills repo has its own package.json:

cd <skills-repo-root> && npm install
npx mantle-cli --help

Golden rule: every command MUST end in --json so the output is machine-parseable. Never enable or connect the mantle-mcp MCP server.

Discover available commands & whitelisted assets/protocols

The mantle-cli catalog is the single source of truth for capabilities, supported tokens, pools, routers, and pool params. Do NOT rely on hard-coded lists, prior knowledge, or cached assumptions.

mantle-cli catalog list --json           # list all capabilities
mantle-cli catalog search "swap" --json  # find capabilities by keyword
mantle-cli catalog show <tool-id> --json # full details for one capability
mantle-cli swap pairs --json             # all whitelisted swap pairs + bin_step / fee_tier
mantle-cli lp find-pools --token-a A --token-b B --json   # discover pools for a pair

Each catalog entry includes category (query / analyze / execute), auth (none / optional / required), cli_command template, and workflow_before (which tools to call first).

Catalog-first constraint (MANDATORY — Hard Constraint #8)

Before executing ANY operation, you MUST consult the catalog to verify the operation exists and retrieve its exact CLI command template. This is a non-negotiable hard constraint at the same level as constraints 1–7.

⛔ ABSOLUTE RULE: No catalog lookup → No execution. No exceptions.

1. Every session MUST start with a catalog load. Run mantle-cli catalog list --json at the beginning of the session to load the full capability list. Do NOT proceed with any operation until the catalog response is received and parsed.
2. Every operation MUST be verified against the catalog before execution. Before running any swap / lp / aave / approve command:
   • Run mantle-cli catalog show <tool-id> --json to retrieve the exact command template, required parameters, and workflow_before dependencies.
   • If the operation is not in the catalog → STOP and refuse. The operation does not exist.
3. Unknown token, pool, or pair? Verify via mantle-cli swap pairs --json or mantle-cli lp find-pools --json. If not in the response → STOP and refuse. It is not whitelisted.
4. Never invent CLI subcommands or flags. If catalog list does not show a capability for the user's request, that capability does not exist. Do NOT guess command names, flags, or parameter formats. Do NOT extrapolate from other commands.
5. Catalog data expires at session boundary. Do NOT carry over catalog results from a previous session — always re-fetch.

Incident reference: Agent skipped catalog lookup, assumed mantle-cli transfer send-token existed, and attempted to construct a transfer command that does not exist in the CLI. Had the agent consulted catalog list first, it would have found zero matches and refused.

Hard Constraints (8 critical rules)

Full rationale, incident reports, and the numbered detail list live in references/safety-prohibitions.md. The eight non-negotiables:

1. CLI only — never enable mantle-mcp; every command ends in --json.
2. 🛑 STOP on ANY mantle-cli error — never auto-retry, never improvise. Print the raw error to the user verbatim, halt the workflow, and recommend the user restart the OpenClaw agent before continuing. Continuing past an unhandled error risks duplicate broadcasts, stale allowances, and fund loss.
3. 🛑 Refuse anything beyond the standard CLI verbs — execute operations MUST be expressed via swap / approve / lp / aave. Token transfers (native MNT and ERC-20) are NOT supported — refuse. If a request can't map to one of the allowed verbs, STOP and tell the user. NEVER improvise with Python, JS, RPC calls, or utils calldata construction. The user accepting risk is NOT sufficient — the prohibition is absolute.
   • Protocol actions are function calls, NOT transfers. aave supply / borrow / repay / withdraw, swap build-swap, and lp add / remove invoke specific functions on the target contract that mint aTokens, route the trade, or register liquidity. Sending tokens directly to the Aave V3 Pool (0x458F293454fE0d67EC0655f3672301301DD51422), a DEX router, a position manager, or a WETHGateway via ERC-20 transfer() / transferFrom() does NOT trigger those functions — the tokens are permanently locked with no on-chain path to recover. If a user says "supply / deposit / lend X to Aave" or "send X to Aave", use mantle-cli aave supply — never model it as an ERC-20 transfer to the Pool address.
4. Never fabricate calldata or compute wei — the dedicated CLI verbs handle decimal conversion deterministically. NEVER use Python/JS for any encoding.
5. Never build the same tx twice — always pass --sender <wallet> so the response carries an idempotency_key. If a build times out, check mantle-cli chain tx --hash <hash> --json BEFORE rebuilding.
6. 🛡️ Always quote before swap — amount-out-min MUST come from the quote's minimum_out_raw, VERBATIM — see "Slippage Protection Rules" section below for full details. Setting --amount-out-min to 0, 1, or any value less than minimum_out_raw is absolutely prohibited — it removes slippage protection and exposes the user to sandwich attacks and fund loss.
7. "sign & WAIT" — verify each tx (status: success) before building the next. Do NOT pipeline unsigned transactions.
8. 🔍 Catalog-first — ALWAYS consult the catalog before ANY operation — run mantle-cli catalog list --json at session start and mantle-cli catalog show <tool-id> --json before each operation. No catalog lookup → no execution. See "Catalog-first constraint" section above for full rules.

⚠ USDT ≠ USDT0

USDT and USDT0 are two different ERC-20 tokens on Mantle (different contract addresses, different protocol support, different liquidity pools). Never confuse them.

• Aave V3 only accepts USDT0 — NOT USDT. If the user only holds USDT, swap to USDT0 on Merchant Moe (bin_step=1) first.
• When the user says "USDT", always clarify — ask whether they mean USDT or USDT0 before executing any operation. Do not assume.
• CLI params must be exact — --in USDT and --in USDT0 point to different contracts. Using the wrong symbol causes failed txs, wrong pools, or fund loss.
• Always display both balances when the user asks about USDT holdings or portfolio.

🔤 Asset Alias Resolution

Generic name → Mantle-whitelisted canonical token. Verify the candidate via mantle-cli swap pairs --json (swap/LP) or aave markets --json (lending) before use — swap support does NOT imply Aave support. Multiple candidates → ASK, never pick silently. Generic balance queries ("how much BTC/ETH?") → list ALL variants.

• BTC / 比特币 → FBTC (only). Refuse WBTC / solvBTC / renBTC.
• ETH / 以太坊 → WETH, mETH (LST), cmETH (restaked mETH) — ask which. Refuse stETH / wstETH / rETH.
• 稳定币 / stablecoin / USD → USDC, USDT0, USDe, sUSDe — ask which + which protocol.
• USDT → clarify USDT vs USDT0 (§USDT ≠ USDT0).
• MNT → native MNT (wrap/unwrap only) or WMNT (swap / LP / Aave).

🛡️ Slippage Protection Rules (Hard Constraint #6 — detailed)

⛔ --amount-out-min MUST equal the quote's minimum_out_raw, passed VERBATIM. No exceptions.

• minimum_out_raw is a raw integer in the output token's smallest unit. The CLI already handles decimal conversion — do NOT multiply, divide, or re-encode it.
• Prohibited values: 0, 1, or anything below minimum_out_raw. These remove slippage protection and expose the user to sandwich attacks.
• If build-swap reverts: re-quote to get a fresh minimum_out_raw and retry — NEVER lower amount-out-min to "make it work." After 2 failed retries, STOP and inform the user.

Incident: Agent re-multiplied minimum_out_raw: 9934699 → passed 9934700000 → revert → fell back to --amount-out-min 1 (zero protection). Correct fix: pass 9934699 verbatim.

Workflow Execution Rules (mandatory)

These rules apply to every workflow (Swap, LP, Aave) and every reference file. Violations may cause irreversible fund loss.

Rule W-1: Strict Sequential Step Enforcement

Each workflow defines a numbered step sequence. You MUST execute steps in exact order — skipping, reordering, or parallelising steps is prohibited.

• NEVER skip an intermediate step to jump to a later one. For example, you MUST NOT call swap build-swap (Step 5) without first completing the quote (Step 2) and allowance check (Step 3).
• NEVER execute a step before its predecessor has completed successfully (on-chain status: success for write operations, valid JSON response for read operations).
• If a step fails, follow STOP CONDITION 1 (references/safety-prohibitions.md). Do NOT skip the failed step and continue with later steps.
• If a step's precondition is not met (e.g. allowance already sufficient at Step 3), the step may be explicitly marked as skipped with reason in the output to the user, but execution must still proceed to the next sequential step — never jump ahead by more than one step.

Rule W-2: User Confirmation Gate Before Transaction Execution

For any on-chain transaction (approve, swap, LP add/remove, Aave supply/borrow/repay/withdraw/set-collateral, wrap/unwrap), you MUST present a Transaction Confirmation Summary and receive explicit user approval before signing.

The summary MUST include:

1. Intent — One-sentence description of what the user asked for.
2. Transaction details — Operation type, input/output tokens & amounts (with USD estimate), recipient address, slippage protection, price impact, gas estimate.
3. Risk warnings — Price impact > 0.2%, large approvals, Isolation Mode caveats, etc.

Format:

⚠️ Transaction Confirmation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Intent:     <what the user asked for>
Operation:  <Swap / Approve / Supply / ...>
Input:      <amount> <token> (≈ $<usd>)
Output:     <expected_amount> <token> (≈ $<usd>)
Min output: <amount_out_min> <token>
Impact:     <price_impact>%
Recipient:  <address>
Est. gas:   <gas> MNT
Warnings:   <any risks>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proceed? (yes/no)

• NEVER broadcast without user confirmation. "no" or no response → STOP.
• Each transaction needs its own confirmation — do NOT batch (e.g. approve and swap are confirmed separately).
• This applies even in auto-mode — every fund-moving tx requires explicit human approval.

Rule W-3: Rate Limiting

• Minimum 2-second gap between consecutive mantle-cli calls. Never fire CLI commands in rapid succession.
• No parallel CLI calls — wait for the previous command's response before issuing the next.
• After any write tx is confirmed, wait at least 5 seconds before the next write command to allow on-chain state (balances, allowances, positions) to settle.
• On ANY mantle-cli non-zero exit (including RPC timeout / rate-limit): STOP immediately per STOP CONDITION 1. Do NOT auto-retry write commands (approve, swap build-swap, wrap-mnt, unwrap-mnt, lp add/remove/collect-fees, aave supply/borrow/repay/withdraw/set-collateral) — re-running a build or sign step after a timeout risks a duplicate broadcast with stale state.
• Post-sign receipt polling is the ONLY permitted retry path — if the tx was already signed and broadcast (you have a hash), you MAY retry mantle-cli chain tx --hash <hash> --json until you get a deterministic status: success | reverted. Rebuilding / re-signing is governed by Rule W-8 only.

Rule W-4: Post-Operation Balance Verification (MANDATORY)

After any write tx confirms (status: success), ALWAYS run mantle-cli account balances <wallet> --json to fetch actual on-chain balances (full-whitelist coverage per Rule W-7). NEVER report, display, or infer balance changes from your own calculation — only show what the CLI returns. Fabricated or estimated balances are prohibited.

Rule W-5: Swap Direction Disambiguation ⚠️

When the user says "use X to get N Y", "swap X for N Y", or "buy N Y with X":

• N is the output quantity (Y tokens to receive) — NOT the input amount.
• ❌ Wrong: "use MNT to get 10 USDC" → interpreted as "swap 10 MNT → USDC"
• ✅ Correct: "use MNT to get 10 USDC" → target output ≈ 10 USDC
• ✅ Converse: "swap 10 MNT for USDC" → input = 10 MNT (output variable). The number attaches to the side it's adjacent to — never flip it.

Estimating the input amount (the CLI only supports fixed-input swaps). Do NOT guess how much X is needed to receive N Y. Instead, use a reverse swap-quote to derive the estimate from live on-chain liquidity:

1. Call mantle-cli defi swap-quote --in Y --out X --amount N --provider best --json — this asks "if I swapped N Y back to X right now, how much X would I get?", which is a good proxy for the X needed to buy N Y.
2. Take the quoted X amount and add a small buffer (suggest +0.5%–1%) to cover slippage, fees, and price impact asymmetry between the two directions. This buffered X is the input for the real forward swap.
3. In the Transaction Confirmation Summary (Rule W-2), clearly state: input = <buffered X>, expected output ≈ N Y (may be slightly higher or lower), and the buffer %. Let the user approve or adjust the buffer before you broadcast.
4. If the user insists on receiving exactly N Y (not ≈ N Y), inform them the CLI has no fixed-output swap and the reverse-quote method is the closest feasible approach — never silently claim exact output, and never flip input/output to fake a fixed-output swap.

Rule W-6: Allowance Disclosure & Approve Confirmation

After every allowances check, display the current allowance (raw + human-readable), spender address, and the required amount for the planned operation to the user BEFORE deciding to approve or skip. If approve is required, present the exact spender address and approval amount in the Transaction Confirmation Summary (Rule W-2) for explicit user approval. Do NOT silently approve (max or otherwise), and do NOT silently skip approve based on your own reading of the allowance.

Rule W-7: Full-Whitelist Balance Query

When querying balances without a specific asset filter, you MUST return all whitelisted assets — never omit any. Procedure:

1. Run mantle-cli account balances <wallet> --json without token filters.
2. Cross-check the response against the whitelisted token list from mantle-cli catalog list --json (or mantle-cli swap pairs --json).
3. For any whitelisted asset missing from step 1's output, query it explicitly and merge the result.

Silently omitting any whitelisted asset (e.g., MOE) from a balance report is a hard error — never present an incomplete portfolio.

Rule W-8: Signing Flow Integrity 🔐

Canonical path: mantle-cli build → pass signable_tx verbatim to Privy API (sign evm-transaction --transaction) → broadcast → wait for on-chain receipt. No shortcuts, no alternatives.

Two views, one transaction. Every mantle-cli build command returns both:

unsigned_tx: {                    // Signer-agnostic view. Use for logging / diffing / non-Privy signers (viem, ethers).
  to: string;
  data: string;
  value: string;                  // hex ("0x0")
  chainId: number;                // INTEGER (e.g. 5000)
  gas?: string;
  maxFeePerGas?: string;
  maxPriorityFeePerGas?: string;
  nonce?: number;                 // INTEGER
  // no `from` field
};

signable_tx: {                    // Privy-ready view. This is what Privy's `--transaction` parameter consumes.
  from: string;                   // sender wallet address — already filled in
  to: string;
  data: string;
  value: string;                  // hex
  chainId: string;                // HEX STRING (e.g. "0x1388")
  gas?: string;
  maxFeePerGas?: string;
  maxPriorityFeePerGas?: string;
  nonce?: string;                 // HEX STRING (e.g. "0xc6")
};

• Privy signing MUST consume signable_tx. Extract it with jq -c .signable_tx <file> and pass it verbatim as --transaction. Never hand-convert unsigned_tx (chainId/nonce int→hex, appending from, etc.) — that conversion is precisely the error class signable_tx was added to eliminate.
• Never mutate, strip, or re-encode any field in signable_tx. No wrapping in {"params":[…]}. No casing changes. No field omission. Byte-for-byte what the CLI emitted.
• Never hand-assemble either object from your own values — the CLI is the sole producer. Fabricating to / data / value / gas params is the same violation as Hard Constraint #4 (no fabricated calldata).
• If the CLI output lacks a signable_tx field (older binary, malformed response), STOP. Do NOT fall back to manually transforming unsigned_tx — upgrade the CLI and rebuild. Silent manual conversion is what caused the ~10-round sign retries in past runs.

One signable_tx = one signature. No exceptions.

• After signing, WAIT for the receipt (mantle-cli chain tx --hash <hash> --json) before any further action.
• On 504 / timeout / network error: do NOT re-sign. First query the chain for the receipt — if the tx is already mined (any status), resume from there; only if it is truly absent from the chain may you rebuild via mantle-cli (new idempotency_key) and sign the new signable_tx. Re-signing the old one risks duplicate broadcast and nonce collision.
• If Privy timed out before returning a tx hash (signing-stage failure, no broadcast): there is nothing to query on-chain. Rebuild via mantle-cli with a new idempotency_key and sign the fresh signable_tx. Discard the old one.
• If Privy rejects the request with a format error (e.g. "chainId must start with 0x", "value must be hex"): do NOT start hand-patching fields. Assume the signable_tx extraction was wrong (e.g. double-serialization, accidental wrapping). Re-extract from the build output file with jq -c .signable_tx and retry exactly once. Two consecutive rejections → STOP and surface the raw error.

Rule W-9: Pre-Execution Readiness Check (MANDATORY)

⛔ Balance AND allowance are TWO separate mantle-cli tool calls — never merged into one pipeline. The allowance value MUST come from mantle-cli account allowances --json, not from a piped script or inference. Completing only the balance check is a hard error.

Before executing ANY write operation (swap, approve, lp add/remove, aave supply/borrow/repay/withdraw/set-collateral, wrap/unwrap), confirm the user's intent is feasible against actual on-chain state. Two queries, in this order:

1. Balance check — mantle-cli account token-balances <wallet> --json. Verify balance(input_token) ≥ planned input amount (for wrap/unwrap: native MNT for wrap, WMNT for unwrap). If insufficient → STOP, report the actual balance to the user, do NOT proceed.
2. Allowance check — mantle-cli account allowances <wallet> --pairs <token>:<spender> --json. Verify allowance(input_token, spender) ≥ planned input amount. If insufficient → route to the approve flow (Rule W-6). Do NOT silently skip.

These checks MUST occur BEFORE the Transaction Confirmation Summary (Rule W-2) — the summary presented to the user MUST reflect real on-chain state, not assumptions. Starting a write op without both queries is a hard error.

Skip conditions (narrow): balance check is not required for pure read ops; allowance check is not required for native-MNT-only ops (e.g. swap wrap-mnt) or for protocols the user has no intent of touching. When in doubt, run both.

Incident: Agent piped account token-balances through python3 -c "..." which printed USDC: 3.408142 Current allowance: 0.5. The CLI only queried balances — the 0.5 did not come from account allowances and is unauditable. Correct fix: two separate mantle-cli ... --json tool calls.

Available Tools

Tool	Purpose	Command
Catalog	Discover capabilities, tokens, pools	mantle-cli catalog list / search / show
Swap	DEX exchange	mantle-cli swap pairs / wrap-mnt / unwrap-mnt / build-swap + mantle-cli defi swap-quote
LP	Liquidity provision	mantle-cli lp top-pools / find-pools / add / remove / collect-fees + mantle-cli defi analyze-pool + mantle-cli lp suggest-ticks
Aave	Lending / borrowing	mantle-cli aave supply / borrow / repay / withdraw / set-collateral / positions
Account	Read state	mantle-cli account allowances / balances + mantle-cli chain tx / estimate-gas

Token transfers are NOT in the toolset. mantle-cli transfer send-native / transfer send-token and the corresponding mantle_buildTransferNative / mantle_buildTransferToken MCP tools have been deliberately removed. Refuse transfer requests per Hard Constraint #3 — do NOT fall back to the utils pipeline to simulate one.

No escape hatch. If a user's request can't be expressed by the verbs above, refuse (see Hard Constraint #3). Do NOT use Python, JS, raw RPC, or utils calldata construction.

When to Use

• Swap tokens on Mantle (Agni, Fluxion, Merchant Moe)
• Add / remove liquidity on a whitelisted DEX
• Supply / borrow on Aave V3
• Discover available assets, pools, or trading pairs (via catalog / swap pairs / lp find-pools)
• Optimize portfolio value (yield, leverage, exit timing)
• Any DeFi operation that is part of the Mantle asset accumulation competition (OpenClaw / 龙虾活动)

Routing Priority (MANDATORY)

This skill is the SOLE entry point for all Mantle asset accumulation competition operations. Any request that matches the conditions below MUST be handled by this skill — do NOT delegate to $mantle-defi-operator or any other skill:

• The user mentions OpenClaw, 龙虾, asset accumulation competition, or the competition wallet
• The user requests swap / LP / Aave / approve / wrap / unwrap on Mantle with a competition context
• The user asks to check balances, positions, or portfolio value in a competition context
• The user asks to optimize portfolio value, yield strategy, leverage, or exit timing for the competition

Why? $mantle-defi-operator produces execution-ready plans but does NOT enforce the safety constraints (STOP-on-error, sign-and-WAIT, user confirmation gates, CLI-only, no fabricated calldata) that are critical for real fund operations in the competition. Routing competition operations to $mantle-defi-operator bypasses these guardrails and risks duplicate broadcasts, stale allowances, and fund loss.

If a non-competition Mantle DeFi request arrives (e.g. general protocol comparison, venue discovery without execution intent), delegate to $mantle-defi-operator.

Intent Routing — 自然语言 → Workflow

Map the user's phrase (中/EN) to a CLI namespace BEFORE any call. Ask when ambiguous.

• 兑换 / 交易 / 买 / 卖 / swap / trade → swap + defi swap-quote (§Swap)
• 包装 / wrap / unwrap MNT → swap wrap-mnt / unwrap-mnt (§Swap)
• 添加 / 提供流动性 / 做市 / add LP → lp top-pools → find-pools → defi analyze-pool → suggest-ticks → add (§Add Liquidity, references/lp-workflow.md)
• 移除流动性 / remove LP / collect fees → lp positions / remove / collect-fees
• 存 / 借 / 还 / 取 (Aave) / supply / borrow / repay / withdraw → aave <verb> / set-collateral (§Aave)
• 授权 / approve → approve (embedded per workflow)
• 余额 / 仓位 / balance / positions → account balances / allowances, aave positions, lp positions (read-only)

Disambiguation: "USDT" → clarify USDT vs USDT0 (§USDT ≠ USDT0). Generic "BTC / ETH / stable" → §Asset Alias. "提供流动性" with no pair → start at lp top-pools, NOT lp add. "存到 Aave / 转到 PositionManager" → function-call verb, NEVER ERC-20 transfer (Hard Constraint #3).

Workflow: Swap (skeleton)

⚠ Steps MUST be executed in strict order (Rule W-1). Each transaction requires user confirmation (Rule W-2).

0. mantle-cli catalog show mantle_buildSwap --json                     → verify command exists, get template & workflow_before
   ↓ MUST complete before Step 1 (Hard Constraint #8)
1. mantle-cli swap pairs --json                                      → find bin_step / fee_tier
   ↓ MUST complete before Step 2
2. mantle-cli defi swap-quote --in X --out Y --amount N --provider best --json   → minimum_out_raw
   ⚠️ SAVE the `minimum_out_raw` value from the response — pass it VERBATIM to --amount-out-min in Step 5.
      DO NOT convert, multiply, or recalculate. See "Slippage Protection Rules" (Hard Constraint #6).
   ↓ MUST complete before Step 3
3. mantle-cli account allowances <wallet> --pairs X:<router> --json  → allowance check
   ↓ MUST complete before Step 4
4. IF insufficient: mantle-cli approve ...                           → ⚠️ USER CONFIRMATION → sign & WAIT
   ↓ MUST confirm tx success before Step 5
5. ⚠️ USER CONFIRMATION — present Transaction Confirmation Summary:
   - Intent, input/output tokens & amounts, amount_out_min, price impact, gas estimate
   → User must explicitly approve before proceeding
   mantle-cli swap build-swap --provider <dex> --in X --out Y ... --amount-out-min <minimum_out_raw from Step 2, VERBATIM> --sender <wallet> --json
   ⚠️ --amount-out-min MUST be the EXACT `minimum_out_raw` from Step 2. NEVER set to 0, 1, or any lower value.
      If this reverts → re-quote (Step 2), do NOT lower amount-out-min. See "Slippage Protection Rules".
                                                                     → sign & WAIT
   ↓ MUST confirm tx success before Step 6
6. mantle-cli chain tx --hash <hash> --json                          → verify status: success

For MNT input: swap wrap-mnt first, then swap WMNT. For MNT output: swap to WMNT, then swap unwrap-mnt. Full step-by-step with retry logic and edge cases → references/swap-workflow.md.

Workflow: Add Liquidity (skeleton)

⚠ Steps MUST be executed in strict order (Rule W-1). Each transaction requires user confirmation (Rule W-2).

0. mantle-cli catalog show mantle_addLiquidity --json                → verify command exists, get template & workflow_before
   ↓ MUST complete before Step 1 (Hard Constraint #8)
1. mantle-cli lp top-pools --sort-by apr --min-tvl 10000 --json   (OR: lp find-pools for a specific pair)
   ↓ MUST complete before Step 2
2. mantle-cli defi analyze-pool ... --investment N --json         → APR, risk, projections
   ↓ MUST complete before Step 3
3. mantle-cli lp suggest-ticks ... --json                         → wide / moderate / tight
   ↓ MUST complete before Step 4
4. ⚠️ USER CONFIRMATION — present LP Confirmation Summary:
   - Intent, pool, token amounts, tick/bin range, strategy, estimated APR, risk warnings
   → User must explicitly approve before proceeding to approvals
   mantle-cli approve --token A --spender <position_manager>      → sign & WAIT
   ↓ MUST confirm tx success
5. mantle-cli approve --token B --spender <position_manager>      → ⚠️ USER CONFIRMATION → sign & WAIT
   ↓ MUST confirm tx success before Step 6
6. mantle-cli lp add ... --sender <wallet> --json                 → ⚠️ USER CONFIRMATION → sign & WAIT

V3 (Agni / Fluxion) takes --fee-tier, --tick-lower, --tick-upper. LB (Merchant Moe) takes --bin-step, --active-id, --delta-ids, --distribution-x/y. xStocks LP only on Fluxion (USDC pairs, fee_tier=3000). Full args → references/lp-workflow.md.

Workflow: Aave Supply → Borrow (skeleton)

⚠ Steps MUST be executed in strict order (Rule W-1). Each transaction requires user confirmation (Rule W-2).

aave supply is a function call, NOT a transfer. The CLI invokes Pool.supply() which pulls tokens via transferFrom AND mints aTokens. Never "simulate" a supply by constructing an ERC-20 transfer() to the Pool address (0x458F293454fE0d67EC0655f3672301301DD51422) — no aToken is minted, no collateral is recorded, the tokens are locked forever. Same principle for borrow / repay / withdraw: always use the dedicated mantle-cli aave verb.

0. mantle-cli catalog show mantle_aaveSupply --json                  → verify command exists, get template & workflow_before
   ↓ MUST complete before Step 1 (Hard Constraint #8)
1. ⚠️ USER CONFIRMATION — present Supply Confirmation Summary:
   - Intent, asset, amount, on-behalf-of address, expected aToken receipt
   → User must explicitly approve before proceeding
   mantle-cli approve --token X --spender <aave-pool>   → sign & WAIT
   ↓ MUST confirm tx success before Step 2
2. mantle-cli aave supply --asset X --amount N --on-behalf-of <wallet> --sender <wallet> --json
                                                                                       → ⚠️ USER CONFIRMATION → sign & WAIT
   ↓ MUST confirm tx success before Step 3
3. mantle-cli aave positions --user <wallet> --json   → verify collateral_enabled
   ↓ MUST complete before Step 4
4. IF collateral_enabled=NO: mantle-cli aave set-collateral --asset X --user <wallet> --sender <wallet>
                                                                                       → ⚠️ USER CONFIRMATION → sign & WAIT
   ↓ MUST confirm tx success before Step 5
5. ⚠️ USER CONFIRMATION — present Borrow Confirmation Summary:
   - Intent, borrow asset, amount, current health factor, projected health factor, liquidation risk
   → User must explicitly approve before proceeding
   mantle-cli aave borrow --asset Y --amount N --on-behalf-of <wallet> --sender <wallet> --json
                                                                                       → sign & WAIT

Edge cases (Isolation Mode, LTV_IS_ZERO, USDT vs USDT0, repay/withdraw with --amount max): see references/aave-workflow.md.

References

File	Load when
references/swap-workflow.md	First swap of the session, or handling timeout / retry / wrap-mnt
references/lp-workflow.md	Adding / removing liquidity, or suggesting tick ranges
references/aave-workflow.md	Any Aave operation, or troubleshooting collateral / Isolation Mode
references/safety-prohibitions.md	A mantle-cli error occurred, the user requested something outside standard verbs, or you need the full STOP protocol + numbered rule list + incident reports

For full CLI documentation and the live whitelisted asset/protocol list: mantle-cli catalog list --json and mantle-cli catalog show <tool-id> --json.

Integrity Verification

Each release includes integrity.json mapping version → SHA-256 hashes for every file. Verify after download:

python3 -c "
import hashlib, json, os, sys
manifest = json.load(open('integrity.json'))
ok = True
for f, expected in manifest['files'].items():
    actual = hashlib.sha256(open(f,'rb').read()).hexdigest()
    if actual != expected:
        print(f'MISMATCH {f}: expected {expected[:16]}… got {actual[:16]}…')
        ok = False
if ok: print(f'All files verified for v{manifest[\"version\"]}')
else: sys.exit(1)
"

On publish/update: regenerate integrity.json with new hashes and bump version.