@blazephoenix/sdk 1.2.1 → 1.3.0

package/README.md

@@ -15,7 +15,7 @@ npm i @blazephoenix/sdk viem
 
 ## BlazePhoenix in one sentence
 
-BlazePhoenix is the fully on-chain DEX aggregator — the route is computed inside the transaction that executes it — paired with an oracle-free staking engine that proves its own solvency on every transaction. It runs on Base, Ethereum, Optimism, Arbitrum and Robinhood Chain.
+BlazePhoenix is the fully on-chain DEX aggregator — the route is computed inside the transaction that executes it — paired with an oracle-free staking engine that proves its own solvency on every transaction. V2, the generation now in development, targets Base, Optimism, Arbitrum, Robinhood Chain and further L2s and is not planned for Ethereum L1. The V1 generation deployed today runs on Base, Ethereum, Optimism, Arbitrum and Robinhood Chain.
 
 **Swap** in the [app](https://blazephoenix.xyz/?tab=swap) · **integrate** with the [SDK](https://github.com/blazephoenixxyz-crypto/SDK) (`npm i @blazephoenix/sdk`) · **connect an agent** to the [MCP server](https://github.com/blazephoenixxyz-crypto/blazephoenix-mcp) (`https://blazephoenix.xyz/mcp`, no key)
 
@@ -53,12 +53,14 @@ q.amountOut;           // net output after the 0.28% fee (bigint, base units)
 q.checks.verdict;      // Phoenix Check: ok | caution | danger | blocked (fails closed)
 q.version;             // protocol version that answered ('1.0.0' today, '2.0.0' once deployed)
 
-// 2) the swap transaction(s): verified calldata + the approval step if needed
+// 2) the swap transaction(s): calldata verified against the request (swap math; `simulate: true`
+//    asks the Router from `from` whether it settles) + the approval step if needed
 const plan = await blaze.buildSwap({
   chain: 'base', tokenIn: 'WETH', tokenOut: 'USDC', amount: '1.5',
   recipient: me, from: me,           // `from` enables the allowance check
   slippageBps: 50,                   // default 50; never below the on-chain floor
   exact: true,                       // optional: minOut from previewPlanExact (one more eth_call)
+  simulate: true,                    // optional: eth_call the swap from `from`; a revert throws not_executable
 });
 plan.steps;       // [approve?, swap] — { chainId, to, data, value }
 plan.minOut;      // the minimum the Router will enforce for you
@@ -71,6 +73,12 @@ const res = await blaze.execute({ wallet, plan }); // approve → simulate → s
 res.amountOut;                                     // realised, from the Router's Swap event
 ```
 
+The Quoter's `canExecute` is swap math: it does not see what the tokens do to the payer (a transfer tax,
+a per-account cap, the payer's own balance). Whether the bytes settle is answered only by the Router's own
+call from the account that will send them: `simulate(plan, from)`, `buildSwap({ simulate: true })` or
+`execute`. With `simulate: true` and the approval still missing, no eth_call is made: `plan.simulation` is
+`{ ok: false, error.name: 'allowance' }`; send the approval, then simulate again before the swap.
+
 `execute` takes a viem `WalletClient`. The SDK never asks for, stores or touches a key.
 
 ## Your RPC, your way
@@ -100,7 +108,7 @@ Protocol versions are deployments, not SDK versions:
 | version | status | what it is |
 |---|---|---|
 | `1.0.0` | **live** on all five chains | the generation deployed at launch |
-| `2.0.0` | pending | the final Core / Hub / Solver / Quoter / Router from [BlazePhoenix-Dex](https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Dex) (`VERSION()` = `"2.0.0"`) |
+| `2.0.0` | pending | the generation in development (Router, Solver, Hub, Quoter and Gate, with the Core and Math libraries; Balancer V2/V3 and Curve NG are reached through the Gate), targeting Base, Optimism, Arbitrum, Robinhood Chain and further L2s and not Ethereum L1, from [BlazePhoenix-Dex](https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Dex) (`VERSION()` = `"2.0.0"`) |
 
 ```ts
 new BlazePhoenix({ rpc, version: 'latest' }); // default: newest version deployed on each chain
@@ -158,7 +166,9 @@ on-chain floor all match what you asked. Your slippage then only ever **tightens
 ## More
 
 ```ts
-await blaze.quoteExact(req);          // previewPlanExact: every concentrated leg dry-run on the pool
+await blaze.quoteExact(req);          // previewPlanExact: every concentrated leg dry-run on its venue.
+                                      // `exactOut` is net of the protocol fee on every Quoter; `quoterOut` is the
+                                      // scalar exactly as the Quoter returned it (gross of the fee on a 1.x Quoter)
 await blaze.quoteBatch([req1, req2]); // per-item { ok, quote } | { ok:false, error }
 await blaze.getFills({ chain: 'base', lookbackBlocks: 5_000n }); // Swap (+ ExecutionProof on 2.x)
 const stop = await blaze.watchFills({ chain: 'base', onFill: console.log });
@@ -168,7 +178,8 @@ toJSON(quote);                         // bigint → string, for HTTP / queues /
 ```
 
 Pure helpers (no RPC): `buildApproveTx`, `buildWrapTx`, `buildUnwrapTx`, `permit2TypedData`,
-`encodeSwapExactInWithPermit2`, `encodeSwapExactIn`, `verifySwapExactIn`, `minOutFor`,
+`encodeSwapExactInWithPermit2`, `encodeSwapExactIn`, `encodeSwapExactInNative`, `encodeSwapBestExactIn`,
+`decodeSwapExactIn`, `verifySwapExactIn`, `tightenMinOut`, `minOutFor`, `phoenixCheck`,
 `decodeBlazeError`, `toBaseUnits`, `fromBaseUnits`, `deepLink`.
 
 Tokens: `0x` addresses, or the universal symbols `ETH` (native), `WETH`, `USDC` (the chain's
@@ -186,7 +197,7 @@ Every failure, `solvency()` included, is a `BlazeError` with a stable `code`; pr
 | `rpc_chain_mismatch` | the node serves a different chain |
 | `rpc_error` | your node failed (network, rate limit) |
 | `no_route` | the Solver found no executable path (`SolverE(5)`) or the quote reverted |
-| `not_executable` | the Quoter says the route cannot settle now (`canExecute = false`) |
+| `not_executable` | the Quoter's swap math says the route cannot execute now (`canExecute = false`), or, with `simulate: true`, the Router's eth_call from `from` reverts |
 | `calldata_mismatch` | Quoter bytes did not match your request — refused |
 | `min_implausible` | `buildSwap`: `userMinOut` below the quote net of `slippageBps` (or the on-chain floor) |
 | `min_above_exact` | `buildSwap({ exact: true })`: `userMinOut` above `exactOut` less the 50 bps safety margin |

package/dist/index.cjs

@@ -5163,9 +5163,9 @@ var EMBEDDED_DEPLOYMENTS = {
     {
       version: "2.0.0",
       status: "pending",
-      source: "blazephoenixxyz-crypto/Blaze-Phoenix-Dex@07c8563",
+      source: "blazephoenixxyz-crypto/Blaze-Phoenix-Dex@f746a48",
       notes: "Final generation (Core/Hub/Solver/Quoter/Router). Addresses arrive through the registry the day they are deployed.",
-      chains: { 8453: pending(), 1: pending(), 10: pending(), 42161: pending(), 4663: pending() }
+      chains: { 8453: pending(), 10: pending(), 42161: pending(), 4663: pending() }
     },
     {
       version: "1.0.0",
@@ -5658,6 +5658,9 @@ function fromBaseUnits(v, decimals, maxDp) {
 var HEX_ADDR2 = /^0x[0-9a-fA-F]{40}$/;
 var INT = /^\d{1,78}$/;
 var UINT128_MAX = (1n << 128n) - 1n;
+function netExactOutput(version, exactOut) {
+  return featuresOf(version).previewAndEncode ? exactOut : exactOut - (exactOut * BigInt(FEE_BPS) + 9999n) / 10000n;
+}
 var BlazePhoenix = class {
   registry;
   rpc;
@@ -5937,7 +5940,7 @@ var BlazePhoenix = class {
         args: [tIn.address, tOut.address, amountIn],
         ...req.blockNumber !== void 0 ? { blockNumber: req.blockNumber } : {}
       });
-      const net = featuresOf(ctx.dep.version).previewAndEncode ? exactOut : exactOut - (exactOut * BigInt(FEE_BPS) + 9999n) / 10000n;
+      const net = netExactOutput(ctx.dep.version, exactOut);
       return {
         chainId: ctx.chainId,
         version: ctx.dep.version,
@@ -6080,8 +6083,8 @@ var BlazePhoenix = class {
       if (!samePath(ex[0], route)) {
         throw new BlazeError("calldata_mismatch", "previewPlanExact priced a different route than the one to execute");
       }
-      exactOut = ex[1];
-      return ex[1];
+      exactOut = netExactOutput(ctx.dep.version, ex[1]);
+      return exactOut;
     };
     const settleMin = async (p) => {
       let floor = minOutFor(p.netOut, slippageBps, p.ironFloor);
@@ -6181,7 +6184,7 @@ var BlazePhoenix = class {
       }
     }
     const quote = this.buildQuote(ctx, tIn, tOut, amountIn, pv, fb);
-    return {
+    const plan = {
       quote,
       entry,
       encodedBy,
@@ -6195,6 +6198,18 @@ var BlazePhoenix = class {
       steps: approval ? [approval.tx, tx] : [tx],
       ...exactOut !== void 0 ? { exactOut } : {}
     };
+    if (!req.simulate) return plan;
+    if (!from) throw new BlazeError("bad_request", "simulate: true needs `from` (the account that will send the swap)");
+    const simulation = await this.simulate(plan, from);
+    if (!simulation.ok && simulation.error?.name !== "allowance") {
+      const err = simulation.error;
+      throw new BlazeError(
+        "not_executable",
+        `the Router refuses these bytes from ${from}: ${err?.name ?? "revert"}${err?.code !== void 0 ? `(${err.code})` : ""} \u2014 ${err?.reason ?? "execution reverted"}`,
+        { details: { from, error: err } }
+      );
+    }
+    return { ...plan, simulation };
   }
   /** eth_call the swap from `from` on your RPC: the realised amountOut if it
    *  would settle now, or the decoded reason it would revert. */