@blazephoenix/sdk 1.0.1 → 1.2.0

package/README.md

@@ -13,6 +13,31 @@ npm i @blazephoenix/sdk viem
 # or straight from GitHub (builds on install):  npm i github:blazephoenixxyz-crypto/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.
+
+**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)
+
+## Reading guide by level
+
+- **New to DeFi:** [BlazePhoenix in five minutes](https://blazephoenix.xyz/learn/blazephoenix-in-five-minutes), then [What is a DEX aggregator](https://blazephoenix.xyz/learn/what-is-a-dex-aggregator) and [How to swap tokens safely](https://blazephoenix.xyz/learn/how-to-swap-safely).
+- **Comfortable with swaps:** [Anatomy of a DEX aggregator](https://blazephoenix.xyz/learn/anatomy-of-an-aggregator) and [BlazePhoenix vs the established aggregators](https://blazephoenix.xyz/learn/how-we-compare).
+- **Engineers and researchers:** the [Technical Whitepaper v2.3](https://blazephoenix.xyz/whitepaper.md) (DOI [10.5281/zenodo.23084091](https://doi.org/10.5281/zenodo.23084091)), the contract source in [Blaze-Phoenix-Dex](https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Dex) and [Blaze-Phoenix-Staking](https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Staking), and [On-chain quoting](https://blazephoenix.xyz/learn/on-chain-quoting).
+- **Models and agents:** [https://blazephoenix.xyz/llms.txt](https://blazephoenix.xyz/llms.txt) and the [reading guide](https://blazephoenix.xyz/reading-guide.md).
+
+## Trust and verification
+
+Each item links to the place where it can be checked. The full list is at [https://blazephoenix.xyz/trust](https://blazephoenix.xyz/trust).
+
+- **Verified contracts:** source-verified on Sourcify and the chain explorers; every address per chain at [/api/deployments](https://blazephoenix.xyz/api/deployments).
+- **Source available:** the contract source is public under the [Business Source License 1.1](https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Dex/blob/main/LICENSE), converting to GPL-2.0-or-later on 2030-06-01.
+- **Public CI:** [GitHub Actions](https://github.com/blazephoenixxyz-crypto/Blaze-Phoenix-Dex/actions) on every push, including the Certora Prover and Halmos.
+- **Bug bounty:** a [public programme](https://blazephoenix.xyz/bounty) with [credited researchers](https://blazephoenix.xyz/security/researchers) and [published advisories](https://blazephoenix.xyz/security/advisories).
+- **Whitepaper DOI:** [10.5281/zenodo.23084091](https://doi.org/10.5281/zenodo.23084091); papers timestamped with [OpenTimestamps](https://blazephoenix.xyz/provenance/provenance.json).
+- **Contact:** contact@blazephoenix.xyz ([security.txt](https://blazephoenix.xyz/.well-known/security.txt)); official channels at [/official](https://blazephoenix.xyz/official).
+- **Audit status:** an independent external audit is scheduled before launch.
+
 ## Quote → build → execute
 
 ```ts
@@ -33,9 +58,11 @@ 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)
 });
 plan.steps;       // [approve?, swap] — { chainId, to, data, value }
 plan.minOut;      // the minimum the Router will enforce for you
+                  // (your userMinOut as given, when set; refused below the quote net of slippage)
 plan.encodedBy;   // 'quoter' on 2.x (the Quoter's own bytes, verified) · 'sdk' on 1.x
 
 // 3) optional: dry-run on your node, then execute with YOUR wallet
@@ -91,17 +118,20 @@ The SDK adapts to what each version can do (`featuresOf(version)`):
 | on-chain `batchQuote` | parallel previews | ✅ chunked |
 | `ExecutionProof` on every fill (quoted vs realised vs floor) | — | ✅ |
 
-### New deployments reach you without a new SDK release
+### Only pinned addresses are routed to by default
 
 The registry has three layers:
 
 1. **Embedded** — shipped in the package. Non-zero addresses are **pins**: nothing fetched
-   at runtime can move them.
+   at runtime can move them, and by default they are the only Router and Quoter addresses
+   a quote or a swap uses. A new deployment reaches you with a new SDK release.
 2. **Remote** — `GET https://blazephoenix.xyz/api/deployments` (static JSON, refreshed every
    10 min in the background; the first lookup waits at most 3 s). It can only fill what the
    snapshot doesn't know — e.g. the 2.0.0 addresses the day they are deployed — and only for
-   versions that can be verified on-chain (2.x+). Every remote-sourced set is **verified on
-   your RPC before first use**:
+   versions that can be verified on-chain (2.x+). Those versions are listed, but routed to
+   only with `registry: { remoteVersions: true }`: the on-chain check reads the entry's own
+   contracts, so it cannot tell a real deployment from a look-alike. With the opt-in, every
+   remote-sourced set is still **verified on your RPC before first use**:
    code at every address, `VERSION()` matches, and the Quoter, Router and Solver all point at
    the same Hub and Solver. Anything else fails closed (`deployment_unverified`).
 3. **Your overrides** — always win:
@@ -133,7 +163,7 @@ await blaze.quoteBatch([req1, req2]); // per-item { ok, quote } | { ok:false, er
 await blaze.getFills({ chain: 'base', lookbackBlocks: 5_000n }); // Swap (+ ExecutionProof on 2.x)
 const stop = await blaze.watchFills({ chain: 'base', onFill: console.log });
 await blaze.tokenInfo('base', '0x…');  // symbol / name / decimals
-await blaze.solvency();                // the staking engine's proof-of-solvency (Base)
+await blaze.solvency();                // staking proof-of-solvency; `not_deployed` where no engine is registered
 toJSON(quote);                         // bigint → string, for HTTP / queues / LLMs
 ```
 
@@ -158,6 +188,8 @@ Every failure, `solvency()` included, is a `BlazeError` with a stable `code`; pr
 | `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`) |
 | `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 |
 | `deployment_unverified` | a registry deployment failed on-chain verification |
 | `unsupported_by_version` | e.g. native ETH input on a 1.x Router |
 | `not_deployed` / `bad_request` / `wallet_chain_mismatch` / `reverted` | as named |

package/dist/index.cjs

@@ -4738,8 +4738,7 @@ var CHAINS = {
     explorer: "https://basescan.org",
     weth: "0x4200000000000000000000000000000000000006",
     usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-    bzpx: "0x23113e72165a034265Ab8Bf2277CCB7a85Cb7483",
-    staking: "0x3f60C7aa0c36a78D200405feBE143d2Cf3fA0c77",
+    bzpx: "0x053D75c00FdD571538492e3B1686Bd963a0911A7",
     blockTime: 2
   },
   10: {
@@ -5356,6 +5355,7 @@ var Registry = class {
   fetchedAt = 0;
   lastError;
   mode;
+  remoteVersions;
   url;
   ttlMs;
   fetchFn;
@@ -5364,6 +5364,7 @@ var Registry = class {
   overrides = /* @__PURE__ */ new Map();
   constructor(opts = {}, overrides) {
     this.mode = opts.mode ?? "auto";
+    this.remoteVersions = opts.remoteVersions ?? false;
     this.url = opts.url ?? DEPLOYMENTS_URL;
     this.ttlMs = opts.ttlMs ?? 10 * 6e4;
     this.fetchFn = opts.fetchFn ?? globalThis.fetch;
@@ -5495,7 +5496,7 @@ var Registry = class {
     if (!isValidSelector(selector)) throw new BlazeError("bad_request", `bad version selector "${selector}"`);
     const ov = this.overrides.get(chainId);
     const sel = ov?.version && selector === "latest" ? ov.version : selector;
-    const candidates = this.doc.versions.filter((v) => matchesSelector(v.version, sel) && isDeployed(v.chains[chainId])).sort((a, b) => compareVersions(b.version, a.version));
+    const candidates = this.doc.versions.filter((v) => matchesSelector(v.version, sel) && isDeployed(v.chains[chainId])).filter((v) => this.remoteVersions || this.isPinned(v.version, chainId)).sort((a, b) => compareVersions(b.version, a.version));
     const pick = candidates[0];
     if (ov && (ov.router || ov.quoter)) {
       const base = pick ? { ...pick.chains[chainId] } : {
@@ -5515,9 +5516,10 @@ var Registry = class {
     }
     if (!pick) {
       const deployed = this.versionsOn(chainId);
+      const remoteOnly = this.remoteVersions ? [] : deployed.filter((v) => matchesSelector(v, sel) && !this.isPinned(v, chainId));
       throw new BlazeError(
         "not_deployed",
-        `no BlazePhoenix deployment matching version "${selector}" on chain ${chainId}` + (deployed.length ? ` (deployed: ${deployed.join(", ")})` : ""),
+        `no BlazePhoenix deployment matching version "${selector}" on chain ${chainId}` + (deployed.length ? ` (deployed: ${deployed.join(", ")})` : "") + (remoteOnly.length ? ` \u2014 ${remoteOnly.join(", ")} is known only from the fetched registry; update the SDK, or set registry.remoteVersions after checking the addresses yourself` : ""),
         { details: { chainId, selector, deployed } }
       );
     }
@@ -5526,6 +5528,11 @@ var Registry = class {
     const source = src("router") === "remote" || src("quoter") === "remote" ? "remote" : "embedded";
     return { chainId, version: pick.version, status: pick.status, contracts: { ...set }, source };
   }
+  /** Router and Quoter both pinned in this package (not filled by a fetched document). */
+  isPinned(version, chainId) {
+    const src = (k) => this.fieldSource[`${version}|${chainId}|${k}`];
+    return src("router") === "embedded" && src("quoter") === "embedded";
+  }
   latestKnownVersion(selector) {
     const all = this.doc.versions.map((v) => v.version).sort((a, b) => compareVersions(b, a));
     const m = selector ? all.find((v) => matchesSelector(v, selector)) : void 0;
@@ -5773,16 +5780,19 @@ var BlazePhoenix = class {
         return { address: c.weth, native: true };
       case "WETH":
         return { address: c.weth, native: false };
+      // `usdc` holds each chain's one dollar asset: USDG on Robinhood Chain, USDC
+      // elsewhere. The other symbol names a different token there, so it is refused.
       case "USDC":
       case "USDG":
-        return { address: c.usdc, native: false };
+        if (s.toUpperCase() === (chainId === 4663 ? "USDG" : "USDC")) return { address: c.usdc, native: false };
+        break;
       case "BZPX":
         if (c.bzpx) return { address: c.bzpx, native: false };
         break;
     }
     throw new BlazeError(
       "bad_request",
-      `${side}: "${ref}" is not a 0x address or a built-in symbol (ETH, WETH, USDC, BZPX) on ${c.name} \u2014 pass the token address`
+      `${side}: "${ref}" is not a 0x address or a built-in symbol (ETH, WETH, ${chainId === 4663 ? "USDG" : "USDC"}, BZPX) on ${c.name} \u2014 pass the token address`
     );
   }
   async decimalsOf(client, chainId, t) {
@@ -6024,6 +6034,60 @@ var BlazePhoenix = class {
     let encodedBy = "sdk";
     let entry;
     let minOut;
+    let at;
+    if (req.exact) {
+      try {
+        at = await ctx.client.getBlockNumber();
+      } catch (e) {
+        this.wrapReadError(e, "block number");
+      }
+    }
+    const pin = at !== void 0 ? { blockNumber: at } : {};
+    let exactOut;
+    const exactRead = async (route) => {
+      let ex;
+      try {
+        ex = await ctx.client.readContract({
+          address: ctx.dep.contracts.quoter,
+          abi: QUOTER_ABI,
+          functionName: "previewPlanExact",
+          args: [tIn.address, tOut.address, amountIn],
+          ...pin
+        });
+      } catch (e) {
+        this.wrapReadError(e, "exact quote");
+      }
+      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];
+    };
+    const settleMin = async (p) => {
+      let floor = minOutFor(p.netOut, slippageBps, p.ironFloor);
+      let ceil;
+      if (req.exact) {
+        const ex = await exactRead(p.route);
+        ceil = minOutFor(ex, EXACT_MARGIN_BPS, 0n);
+        floor = maxBig(floor, minOutFor(ceil, slippageBps, 0n));
+      }
+      if (userMinOut === 0n) return floor;
+      if (userMinOut < floor) {
+        throw new BlazeError(
+          "min_implausible",
+          `userMinOut is below ${floor} (this quote net of slippageBps): set it from a price you trust, or raise slippageBps if a lower minimum is intended`,
+          { details: { userMinOut: userMinOut.toString(), floor: floor.toString() } }
+        );
+      }
+      if (ceil !== void 0 && userMinOut > ceil && userMinOut > floor) {
+        throw new BlazeError(
+          "min_above_exact",
+          `userMinOut is above ${ceil} (exactOut less ${EXACT_MARGIN_BPS} bps): an honest swap at this minimum may revert`,
+          { details: { userMinOut: userMinOut.toString(), ceiling: ceil.toString() } }
+        );
+      }
+      return userMinOut;
+    };
     if (features.previewAndEncode && !tIn.native && mode === "route") {
       let call;
       try {
@@ -6031,19 +6095,21 @@ var BlazePhoenix = class {
           address: ctx.dep.contracts.quoter,
           abi: QUOTER_ABI,
           functionName: "previewAndEncodeWithMinOut",
-          args: [tIn.address, tOut.address, amountIn, userMinOut, recipient, deadline]
+          args: [tIn.address, tOut.address, amountIn, userMinOut, recipient, deadline],
+          ...pin
         }) : await ctx.client.readContract({
           address: ctx.dep.contracts.quoter,
           abi: QUOTER_ABI,
           functionName: "previewAndEncode",
-          args: [tIn.address, tOut.address, amountIn, recipient, deadline]
+          args: [tIn.address, tOut.address, amountIn, recipient, deadline],
+          ...pin
         });
         [pv, call] = r;
       } catch (e) {
         this.wrapReadError(e, "previewAndEncode");
       }
       assertExecutable(pv, tIn.address, tOut.address, call);
-      minOut = maxBig(minOutFor(pv.netOut, slippageBps, pv.effectiveMinOut), userMinOut);
+      minOut = await settleMin(pv);
       verifySwapExactIn(call, {
         tokenIn: tIn.address,
         tokenOut: tOut.address,
@@ -6057,9 +6123,9 @@ var BlazePhoenix = class {
       encodedBy = "quoter";
       entry = "swapExactIn";
     } else {
-      ({ pv, fb } = await this.readPreview(ctx, tIn.address, tOut.address, amountIn, userMinOut));
+      ({ pv, fb } = await this.readPreview(ctx, tIn.address, tOut.address, amountIn, userMinOut, at));
       assertExecutable(pv, tIn.address, tOut.address);
-      minOut = maxBig(minOutFor(pv.netOut, slippageBps, pv.effectiveMinOut), userMinOut);
+      minOut = await settleMin(pv);
       if (mode === "best") {
         entry = "swapBestExactIn";
         data = encodeSwapBestExactIn(tIn.address, tOut.address, amountIn, minOut, recipient, deadline);
@@ -6106,7 +6172,8 @@ var BlazePhoenix = class {
       slippageBps,
       approval,
       unwrapAfter: tOut.native,
-      steps: approval ? [approval.tx, tx] : [tx]
+      steps: approval ? [approval.tx, tx] : [tx],
+      ...exactOut !== void 0 ? { exactOut } : {}
     };
   }
   /** eth_call the swap from `from` on your RPC: the realised amountOut if it
@@ -6172,6 +6239,12 @@ var BlazePhoenix = class {
         if (r.status !== "success") throw new BlazeError("reverted", `approval transaction reverted (${approvalHash})`);
       }
       plan = { ...plan, approval: { ...plan.approval, current: plan.approval.amount } };
+      if (Date.now() - plan.quote.quotedAt > maxAge) {
+        if (!req) {
+          throw new BlazeError("bad_request", `plan went older than ${maxAge}ms while the approval confirmed${approvalHash ? ` (${approvalHash})` : ""} \u2014 the swap was NOT sent; rebuild the plan, or pass \`request\` so it can be rebuilt`);
+        }
+        plan = await this.buildSwap({ ...req, from: req.from ?? account.address });
+      }
     }
     if (opts.simulate ?? true) {
       const sim = await this.simulate(plan, account.address);
@@ -6341,6 +6414,17 @@ function checkDeadlineSec(n) {
   return n;
 }
 var maxBig = (a, b) => a > b ? a : b;
+var EXACT_MARGIN_BPS = 50;
+function samePath(a, b) {
+  const eqA = (x, y) => x.toLowerCase() === y.toLowerCase();
+  return a.hops.length === b.hops.length && a.hops.every((h, i) => {
+    const g = b.hops[i];
+    return eqA(h.tokenIn, g.tokenIn) && eqA(h.tokenOut, g.tokenOut) && h.legs.length === g.legs.length && h.legs.every((l, j) => {
+      const m = g.legs[j];
+      return eqA(l.pool, m.pool) && eqA(l.hooks, m.hooks) && l.kind === m.kind && l.fee === m.fee && l.tickSpacing === m.tickSpacing && l.zeroForOne === m.zeroForOne && l.stable === m.stable;
+    });
+  });
+}
 function deepLink(opts = {}) {
   const base = (opts.baseUrl ?? "https://blazephoenix.xyz").replace(/\/+$/, "");
   const sp = new URLSearchParams();