@blazephoenix/sdk 1.0.0 → 1.1.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
@@ -64,7 +89,7 @@ new BlazePhoenix();   // reads BLAZEPHOENIX_RPC_BASE / _ETHEREUM / _OPTIMISM / _
 - A chain without a configured node throws `rpc_required` — nothing silently falls back
   to someone else's infrastructure.
 - `https://` and `wss://` only (`http://` allowed for `localhost` — your anvil/geth).
-  URLs are redacted in every error message, because keys live in them.
+  URLs are redacted in every error message and in its `cause` chain, because keys live in them.
 
 ## Versions — pick yours
 
@@ -91,17 +116,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:
@@ -147,7 +175,7 @@ guesses a token from a ticker.
 
 ## Errors
 
-Every failure is a `BlazeError` with a stable `code`; protocol reverts carry `revert`
+Every failure, `solvency()` included, is a `BlazeError` with a stable `code`; protocol reverts carry `revert`
 (`RouterE` / `QuoterE` / `SolverE` / `HubE` + the reason from the contract's own source):
 
 | code | meaning |
@@ -167,6 +195,8 @@ Every failure is a `BlazeError` with a stable `code`; protocol reverts carry `re
 [`@blazephoenix/mcp`](https://github.com/blazephoenixxyz-crypto/blazephoenix-mcp) wraps this SDK as
 a local MCP server — the agent's tools run on your machine, on your RPC.
 
+For agents, [`llms.txt`](llms.txt) describes this package in the [llmstxt.org](https://llmstxt.org) format.
+
 ## Examples
 
 [`examples/`](examples): `quote.ts`, `watch-fills.ts`, `telegram-bot.ts`, and