starchild-swap-and-bridge

OmniRoute — 统一兑换 + 桥接路由器

一个技能即可处理任何“将链 X 上的代币 A 换成链 Y 上的代币 B”的请求。它结合了两个引擎，并选择最佳的完整可执行路径，而不只是最佳报价：

引擎	基础 URL	优势
WOOFi V2	https://sapi.woofi.com	同链兑换最优价格（WooPP + 1inch + ODOS），在 14 条 EVM 链上提供简单跨链。链名 + 代币符号，人类可读金额，无需认证。速率限制 5 req/s。
LayerZero Value Transfer	https://transfer.layerzero-api.com/v1	通过 OFT / Stargate / CCTP / Aori 实现广泛的多链桥接（EVM、Solana、Aptos、TON…）。通过区块浏览器 URL 轮询状态。通过 core.http_client 代理认证。

不要硬编码链/代币覆盖范围的声明——应通过 LayerZero 的 GET /v1/chains 和 GET /v1/tokens，以及下方 WOOFi 的链表实时发现。

步骤 0 — 对请求分类

1. EVM 链上的同链兑换 → WOOFi（/v2/swap）。LayerZero 不做同链兑换。
2. 跨链，两条链都在 WOOFi 的 14 条 EVM 列表中，两种代币都是 ERC-20/原生代币 → 向两个引擎询价，并按步骤 2 中的路径排名规则选择。
3. 任何非 EVM 链（Solana、Aptos、TON、Tron…），或不在 WOOFi 列表中的链，或偏好通过 CCTP 使用原生 USDC → 仅使用 LayerZero。
4. 目的地需要兑换但 LayerZero 无法完成 → 串联引擎：先 LayerZero 桥接，再在目的链上用 WOOFi 兑换（两次确认，两条链上都要 gas——告知用户，并将目的链 gas 纳入比较）。

WOOFi 文档中的 v2 链集合（执行时验证支持情况——将 API 错误视为“不支持”，而非 bug）：arbitrum、base、bsc、polygon、optimism、avalanche、ethereum、linea、mantle、sonic、berachain、hyperevm、monad、zksync。

原生代币处理因引擎而异：

• WOOFi（仅 EVM）： 使用符号（"ETH"、"BNB"、"AVAX"、"POL"、"MNT"、"S"、"BERA"、"MON"）或 EVM 占位地址 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE。
• LayerZero： 不要假设存在通用占位地址。通过 GET /v1/chains（nativeCurrency.address）和 GET /v1/tokens 按链解析原生/代币地址——非 EVM 链（Solana、Aptos、TON…）使用的地址格式完全不同。

步骤 1 — 飞行前验证（两个阶段）

更好的报价仍可能是无法执行的路径。交易构建前无法得知确切的 gas 要求，因此验证分两个阶段进行：

阶段 A — 询价之前：

• 源代币余额足以覆盖卖出金额（在链上获取，使用代币真实的 decimals——切勿假设为 18）。
• 代币身份：同时确认链 ID、代币地址、decimals 和符号。切勿仅信任符号解析，尤其是对未知或未验证的代币——询价前将解析出的地址与发现数据进行交叉核对。
• 目的地址符合目的链的格式，并与用户声明的意图一致（源钱包和目的钱包不同可能是合理的——若不同，需明确确认）。
• 钱包兼容性（大致判断，例如能否签名 EIP-712？能否在 Solana 上签名？）。

阶段 B — 交易构建之后、签名之前：

• 原生 gas 余额足以覆盖实际构建的步骤：授权 gas + 兑换/桥接 gas + 附加的任何 value/native_fee。对于串联路径，还包括目的链 gas。
• 步骤类型在构建的路径中均可由该钱包执行。
• 授权目标和 spender 与 API 生成的 calldata 一致。
• 余额仍然充足，足以覆盖已构建交易中的确切金额。

若任何检查失败，应报告该问题而不是继续执行。

步骤 2 — 询价并比较完整路径

WOOFi（无需认证，人类可读金额）

# Same-chain
curl -X POST "https://sapi.woofi.com/v2/quote" -H "Content-Type: application/json" \
  -d '{"chain": "arbitrum", "sell_token": "USDC", "buy_token": "WETH", "sell_amount": "1000"}'

# Cross-chain
curl -X POST "https://sapi.woofi.com/v2/cross_chain/quote" -H "Content-Type: application/json" \
  -d '{"src_chain": "arbitrum", "dst_chain": "base", "src_token": "USDC", "dst_token": "USDC", "src_amount": "100"}'

LayerZero（代理鉴权，基础单位字符串金额）

密钥由 sc-proxy 注入——不要设置 LAYERZERO_API_KEY；请通过 core.http_client（proxied_post/proxied_get）路由调用。普通 curl 仅适用于无需鉴权的发现端点（/chains、/tokens、/metadata）。

from core.http_client import proxied_post
r = proxied_post(
    "https://transfer.layerzero-api.com/v1/quotes",
    json={
        "srcChainKey": "base", "dstChainKey": "solana",
        "srcTokenAddress": "<src token address, resolved via discovery>",
        "dstTokenAddress": "<dst token address, resolved via discovery>",
        "srcWalletAddress": "<wallet>", "dstWalletAddress": "<dst wallet>",
        "amount": "1000000000000000",  # STRING, token base units per its decimals
        "options": {"amountType": "EXACT_SRC_AMOUNT",
                    "feeTolerance": {"type": "PERCENT", "amount": 2}},
    },
    headers={"x-api-key": "proxy", "SC-CALLER-ID": f"chat:{thread_id}"},
    timeout=40,
)

防御性地处理 LayerZero 响应：

• 响应体可能包含 error、空的 quotes 数组，和/或 rejectedQuotes。将空/错误视为“无路由”，并说明原因（如有拒绝原因请呈现出来）。
• 比较 quotes 中每一个条目的 dstAmount、dstAmountMin、feeUsd 和步骤数量——不要盲目采用 quotes[0]。
• 检查每个 quote 的 userSteps 中的步骤类型：交易步骤 vs 签名（EIP-712）步骤。只选择钱包能够执行的步骤类型的路由。
• Quote 会过期——跟踪其时效，若执行延迟则重新 quote。

比较规则

• 绝不要从目标代币数量中减去 feeUsd。 以人类可读代币单位比较目标输出（使用目标代币的 decimals 转换 LayerZero 基础单位；WOOFi 金额已是人类可读的）。
• 最小收到量是金额，不是价格。 LayerZero 直接以 dstAmountMin 返回它。WOOFi 的 guaranteed_price 是一个价格：将 WOOFi 的最小输出计算为 guaranteed_price × sell_amount（或使用响应中返回的最小输出字段，如果提供的话）。绝不要把这两个字段当作等价物呈现。
• 分别展示以下内容，绝不要混合成一个数字：
  • 协议目标输出（预期）
  • 最小收到量，以目标代币单位计（按上述方式计算）
  • 源链上的原生 gas 成本（如为链式路由，还包括目标链上的）
  • 跨链桥/协议费用（feeUsd、native_fee）
  • 输出的预估 USD 价值（仅供参考）
• 排名时需考虑授权 gas，以及链式路由中目标链兑换的 gas 和滑点。

路由排名（无固定引擎偏好）

按以下权重顺序对候选路由排名：

1. 净目标价值，定义为： 输出 USD 价值 − 源链 gas USD − 目标链 gas USD − 协议费用 USD。 代币和原生 gas 的 USD 价格必须来自明确的实时来源（例如来自 LayerZero /v1/tokens 的代币 price.usd，或比较中注明的其他实时价格源）。如果无法获得可靠的实时价格，不要声称有确定的净价值赢家——呈现每条路由的原始数据，让用户选择。
2. 最小收到量（最坏情况保护）
3. 所有必需交易的总 gas
4. 预估时长
5. 签名/交易数量和路由可靠性——当输出接近时，优先选择交易更少、失败点更少的路由
6. 滑点敞口

呈现比较结果，并在签署任何内容之前获得用户的明确确认。

步骤 3 — 执行

⚠️ 授权顺序 — 绝不盲目沿用原始的 tx_steps

授权确认后，重建交易：自原始响应构建以来，报价、calldata、授权额度状态和路由条件可能已发生变化，执行过期的步骤可能导致回滚（已在实盘测试中观察到）。对于 WOOFi 同链和跨链路由均适用：

1. 若 needs_approve 为 true，先仅发送授权步骤。
   • 签名前，验证授权对象的 to 是卖出代币的合约，且被授权的 spender 与 API 生成的 calldata 中的 spender 一致。尽可能使用精确金额授权 — 绝不要无限授权。
2. 等待授权交易在链上确认。
3. 重新调用 /v2/swap（或 /v2/cross_chain/swap）以重建交易。
4. 验证新响应中 needs_approve: false。
5. 执行新的兑换步骤。若仍报告需要授权，停止并上报 — 不要循环重试。

同样的原则适用于 LayerZero userSteps：授权步骤确认后，在发送跨链交易前，优先重新生成步骤（POST /v1/build-user-steps，请求体为 {"quoteId": ...}），并且对 Solana 始终重新生成（blockhash 约 60 秒过期）。

每次签名之前

解码并向用户展示：目标合约、链、代币、金额、spender（授权场景）以及附带的原生 value。执行护栏：最大总费用、最大滑点、最小接收量 — 若新交易违反已确认的内容，则中止。

确认有效性： 仅当金额、目标地址、spender、滑点、最小接收量和总费用均保持在用户已批准的限额内时，重建/新的报价才可在不再次询问用户的情况下执行。上述任何一项发生实质性变化，均需重新确认。

LayerZero 步骤类型

• 交易步骤： 按顺序签名并发送，步骤之间等待确认。
• 签名步骤（AORI/intent）： 对 userStep.signature.typedData 中的 EIP-712 负载进行签名，然后调用 POST /v1/submit-signature，请求体为 {"quoteId", "signatures": ["0x..."]}。
• AA 钱包： 若钱包仅返回 user_operation_hash，需将其解析为最终的链上交易哈希 — 优先通过 bundler 回执（若可用），否则通过钱包交易历史或目标转账记录。缺少 bundler 回执并不构成失败的证据：绝不要仅因回执不可用就将转账标记为失败；应回退到链上验证。

第 4 步 — 验证完成（而不仅仅是“交易已发送”）

成功需要满足以下所有条件，而不仅仅是一个区块浏览器链接：

1. 源交易已确认（最终 tx hash，而非 user-op hash）。
2. 源钱包实际扣除了预期金额。
3. 目标回执 — 主要证据是目标交易回执及其代币 Transfer 日志（金额、接收方、代币合约）。仅将目标钱包的余额变化作为佐证：无关的并发转账可能使仅基于余额的检查失真，且对于原生资产，余额变化还会因目标链 gas 或其他活动而偏移。将收到的金额与最小接收量比较 — 若低于则标记。
4. 以人类可读单位上报实际收到的目标金额。

轮询：

• LayerZero： 每约 4 秒调用 GET /v1/status/{quoteId}?txHash=0x...（经代理）。 终态：SUCCEEDED、FAILED、UNKNOWN；非终态：PENDING、PROCESSING。 分享 explorerUrl — 但仍需执行上述目标回执/日志验证。
• WOOFi 跨链： LayerZeroScan（https://layerzeroscan.com/tx/<hash>）仅作为跟踪辅助 — 完成由目标回执/日志验证确认。
• 链式流程（跨链 → 兑换）： 仅在跨链被验证完成（资金可见）后，才启动目标链上的 WOOFi 兑换，然后在目标链上再次执行完整的授权-重新报价流程。

安全规则

• ⚠️ **切勿批准 LZMulticall（Wrapper）合约作为代币支出者。**按原样执行 API 返回的步骤；切勿手动构造授权。
• 优先使用精确金额授权；切勿使用无限额度。
• 报价会过期 — 若执行延迟，请重新获取报价；切勿复用过期报价。
• 在请求用户确认前，检查源代币余额和原生 gas 余额。
• 速率限制：WOOFi 5 req/s；LayerZero 状态轮询保持在约 4s 的间隔。
• **切勿自动重试失败交易。**在 revert、FAILED 或 UNKNOWN 时，报告交易哈希 / explorerUrl 以及可用的解码原因， 然后等待用户。
• 在每次签名前，说明链、代币、金额、费用、支出者和目标地址；根据最新报价重新核验护栏，而非原始报价。

发布前测试关卡

在将部署视为可投入生产之前，须通过以下实盘测试： 同链 ERC-20→ERC-20；原生→ERC-20 和 ERC-20→原生；跨链同代币 EVM→EVM；跨链代币转换；仅 LayerZero 的 EVM→Solana 和 Solana→EVM； 先桥接再目标链兑换；已有授权和需要授权的路径； 代币不足和 gas 不足；报价过期、兑换 revert、桥接失败、 目标链延迟；源钱包与目标钱包不同；AA 钱包仅返回 user_operation_hash。