starchild-swap-and-bridge

OmniRoute — 統合スワップ + ブリッジルーター

「チェーン X 上のトークン A をチェーン Y 上のトークン B にしたい」というあらゆるリクエストに対応する単一のスキルです。2 つのエンジンを組み合わせ、単なる最良の見積もりではなく、最良の実行可能な完全ルートを選択します:

エンジン	ベース 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 スワップ（2 回の確認、 両方のチェーンでガス — ユーザーに伝え、比較に宛先のガスを含めます）。

WOOFi のドキュメントに記載された v2 チェーンセット（実行時にサポートを検証してください — API エラーはバグではなく「未サポート」として扱います）: 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 — 事前検証（2 段階）

より良い見積もりでも、実行不可能なルートである可能性があります。正確なガス要件は トランザクション構築前には不明であるため、検証は 2 段階で行います:

ステージ A — 見積もり前:

• ソーストークンの残高が売却額をカバーしていること（トークンの実際の decimals を使用して オンチェーンで取得 — 18 と仮定しないでください）。
• トークンの同一性: チェーン ID、トークンアドレス、decimals、シンボルをまとめて確認します。 特に未知または未検証のトークンでは、シンボルの解決だけを信頼しないでください — 見積もりの前に、解決されたアドレスを検出データと照合してください。
• 宛先アドレスが宛先チェーンの形式に対して有効であり、ユーザーの 表明した意図と一致していること（ソースと宛先のウォレットは正当に異なる場合があります — 異なる場合は明示的に確認してください）。
• ウォレットの互換性を大まかに確認すること（例: EIP-712 に署名できるか? Solana で 署名できるか?）。

ステージ B — トランザクション構築後、署名前:

• ネイティブガス残高が実際に構築されたステップをカバーしていること: 承認ガス + スワップ/ブリッジガス
  • 付随する value/native_fee。チェーンされたルートでは、宛先チェーンのガスも含みます。
• 構築されたルート内のステップタイプがすべてウォレットで実行可能であること。
• 承認のターゲットとスペンダーが 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] を盲目的に採用しないでください。
• 各クォートの userSteps を検査してステップの種類を確認してください：トランザクションステップか署名 （EIP-712）ステップか。ウォレットが実行できるステップ種別のルートのみを選択してください。
• クォートには有効期限があります — 経過時間を追跡し、実行が遅れる場合は再クォートしてください。

比較ルール

• 宛先トークン数量から feeUsd を差し引かないでください。 宛先の 出力は人間が読めるトークン単位で比較してください（LayerZero のベース単位は宛先 トークンの decimals を使って変換してください。WOOFi の金額はすでに人間が読める形式です）。
• 最小受取額は金額であり、価格ではありません。 LayerZero はそれを dstAmountMin として直接返します。WOOFi の guaranteed_price は価格です：WOOFi の最小 出力を guaranteed_price × sell_amount として計算してください（またはレスポンスが 最小出力フィールドを提供する場合はそれを使用してください）。この 2 つのフィールドを 等価なものとして提示しないでください。
• これらを個別に表示し、決して 1 つの数値に混ぜないでください：
  • プロトコルの宛先出力（予想）
  • 最小受取額（宛先トークン単位、上記のとおり計算）
  • ソース側のネイティブガスコスト（チェーンルートの場合は宛先側も）
  • ブリッジ／プロトコル手数料（feeUsd、native_fee）
  • 出力の推定 USD 価値（参考情報）
• ランキングの際は、承認ガス、およびチェーンルートの場合は宛先スワップのガスと スリッページを考慮してください。

ルートランキング（固定のエンジン優先なし）

候補ルートは、重みの順に次の基準でランク付けしてください：

1. 純宛先価値。次のように定義されます： 出力 USD 価値 − ソースガス USD − 宛先ガス USD − プロトコル手数料 USD。 トークンおよびネイティブガスの USD 価格は、明示されたライブソース（たとえば LayerZero /v1/tokens のトークン price.usd、または比較で名前を挙げた別のライブ価格フィード）から 取得する必要があります。信頼できるライブ価格が利用できない場合は、明確な 純価値の勝者を主張しないでください — ルートごとの生の数値を提示し、ユーザーに選択させてください。
2. 最小受取額（最悪ケースの保護）
3. 必要なすべてのトランザクションにわたる合計ガス
4. 推定所要時間
5. 署名／トランザクションの数とルートの信頼性 — 出力が 近い場合は、トランザクションが少なく障害点が少ないルートを優先してください
6. スリッページエクスポージャー

比較を提示し、何かに署名する前にユーザーの明示的な確認を得てください。

Step 3 — Execute

⚠️ 承認の順序 — 元の tx_steps を盲目的に反復しないでください

承認が確認されたら、トランザクションを再構築してください。見積もり、calldata、allowance の状態、ルーティング条件は、元のレスポンスが構築された時点から変化している可能性があり、 古いステップを実行するとリバートのリスクがあります（ライブテストで確認済み）。WOOFi の同一チェーン ルートとクロスチェーンルートの両方について：

1. needs_approve が true の場合、まず承認ステップのみを送信します。
   • 署名する前に、承認の to が売却トークンのコントラクトであること、および 承認される spender が API 生成の calldata 内の spender と一致することを確認してください。 可能な場合は正確な金額の承認を使用してください — 無制限の allowance は決して使用しないでください。
2. 承認トランザクションがオンチェーンで確認されるまで待機します。
3. /v2/swap（または /v2/cross_chain/swap）を再呼び出しして、トランザクションを再構築します。
4. 新しいレスポンスが needs_approve: false であることを確認します。
5. 新しいスワップステップを実行します。それでも承認が必要と報告される場合は、停止して報告してください — リトライをループしないでください。

同じ原則が LayerZero の userSteps にも当てはまります。承認ステップが確認された後は、 ブリッジトランザクションを送信する前にステップを再生成する（POST /v1/build-user-steps に {"quoteId": ...} を指定）ことを推奨し、Solana の場合は常に再生成してください（ブロックハッシュは 約60秒で失効します）。

すべての署名の前に

ユーザーにデコードして表示してください：宛先コントラクト、チェーン、トークン、金額、spender （承認の場合）、および添付されるネイティブの value。ガードレールを適用してください：最大合計手数料、 最大スリッページ、最小受取額 — 新しいトランザクションが確認済みの内容に違反する場合は中止してください。

確認の有効性： 再構築された／新しい見積もりが、ユーザーに再度確認を求めることなく実行できるのは、 金額、宛先アドレス、spender、スリッページ、最小受取額、および合計手数料がすべて、ユーザーがすでに 承認した範囲内に留まっている場合のみです。これらのいずれかに重要な変更がある場合は、再度の確認が 必要です。

LayerZero のステップタイプ

• トランザクションステップ： 順番に署名して送信し、ステップ間で確認を待機します。
• 署名ステップ（AORI/intent）： userStep.signature.typedData 内の EIP-712 ペイロードに署名し、 その後 POST /v1/submit-signature に {"quoteId", "signatures": ["0x..."]} を送信します。
• AA ウォレット： ウォレットが user_operation_hash のみを返す場合、それを最終的なオンチェーン トランザクションハッシュに解決してください — 利用可能な場合はバンドラーのレシートを介して、 そうでない場合はウォレットのトランザクション履歴または宛先の転送記録を介して解決します。 バンドラーのレシートが存在しないことは失敗の証拠ではありません：レシートが利用できないという だけの理由で転送を失敗とマークしないでください。オンチェーン検証にフォールバックしてください。

ステップ 4 — 完了を検証する（単なる「tx 送信済み」ではなく）

成功には、単なるエクスプローラーのリンクではなく、以下すべてが必要です：

1. ソーストランザクションが確認されている（user-op ハッシュではなく、最終的な tx ハッシュ）。
2. ソースウォレットが実際に期待される金額を引き落としている。
3. 宛先のレシート — 主要な証拠は、宛先トランザクションのレシートとそのトークン Transfer ログ です（金額、受取人、トークンコントラクト）。宛先ウォレットの残高差分は補強証拠としてのみ 使用してください。無関係な同時転送が残高のみのチェックを歪める可能性があり、ネイティブ資産の 場合、差分は宛先のガスやその他のアクティビティによっても歪められます。受取金額を最小受取額と 比較してください — 下回る場合はフラグを立ててください。
4. 受け取った正確な宛先金額を、人間が読める単位で報告してください。

ポーリング：

• LayerZero： GET /v1/status/{quoteId}?txHash=0x...（プロキシ経由）を約4秒ごとに実行します。 終端状態：SUCCEEDED、FAILED、UNKNOWN、非終端状態：PENDING、PROCESSING。 explorerUrl を共有してください — ただし、上記の宛先レシート／ログの検証は引き続き実行してください。
• WOOFi クロスチェーン： LayerZeroScan（https://layerzeroscan.com/tx/<hash>）は追跡補助に すぎません — 完了は宛先レシート／ログの検証によって確認されます。
• チェーン化されたフロー（ブリッジ → スワップ）： ブリッジが完了したことが検証されてから （資金が確認できてから）宛先チェーンの WOOFi スワップを開始し、その後宛先チェーンで 承認→見積もり再取得のシーケンス全体を再度実行してください。

安全ルール

• ⚠️ LZMulticall（Wrapper）コントラクトをトークンの spender として承認しないでください。 API が返したステップはそのまま実行し、承認を手作業で作成しないでください。
• 正確な金額の承認を優先し、無制限のアローワンスは決して使用しないでください。
• クォートには有効期限があります。実行が遅れる場合は再クォートし、古いクォートを再利用しないでください。
• ユーザーに確認を求める前に、ソーストークンとネイティブガスの残高を確認してください。
• レート制限: WOOFi は 5 リクエスト/秒。LayerZero のステータスポーリングは約 4 秒間隔に保ってください。
• 失敗したトランザクションを自動的にリトライしないでください。 リバート、FAILED、または UNKNOWN の場合、tx ハッシュ / explorerUrl と、可能であればデコードされた原因を報告し、その後ユーザーを待ってください。
• 署名のたびに、チェーン、トークン、金額、手数料、spender、送信先アドレスを明示してください。ガードレールは元のクォートではなく、最新のクォートに対して再検証してください。

リリース前テストゲート

デプロイを本番環境対応と見なす前に、以下に関するライブテストに合格してください: 同一チェーンの ERC-20→ERC-20、ネイティブ→ERC-20 および ERC-20→ネイティブ、クロスチェーンの同一トークン EVM→EVM、クロスチェーンのトークン変換、LayerZero のみの EVM→Solana および Solana→EVM、 ブリッジ後の送信先スワップ、既存アローワンスおよび承認必須のパス、 トークン不足およびガス不足、クォートの期限切れ、リバートされたスワップ、失敗したブリッジ、 遅延した送信先、ソースウォレットと送信先ウォレットの相違、user_operation_hash のみを返す AA ウォレット。