sally-defi-ts-sdk 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sally (sally.tools)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+<div align="center">
+
+<img src="assets/header.svg" alt="sally-defi-ts-sdk · TypeScript SDK" width="100%">
+
+# sally-defi-ts-sdk · TypeScript SDK
+
+**One client for CrossHybrid swaps & liquidity on Base + BSC.**
+
+Wraps the live [Sally](https://sally.tools) v2.0.2 protocol — best-route hybrid
+swaps, V2·V3·V4·Slipstream liquidity, 1e18 USD pricing, honeypot screening, locks
+and referral fees — behind one typed, beginner-friendly and AI-agent-ready API.
+
+**100% on-chain — no API, no subgraph, no backend.**
+
+[Website](https://sally.tools) · [Docs](docs/) · [Examples](examples/) · `support@sally.tools`
+
+> A faithful 1:1 TypeScript port of the [sally-defi-py-sdk](https://github.com/SallyTools/sally-defi-py-sdk) (`v0.3.2`, deployment `v2.0.2`), built on [ethers v6](https://docs.ethers.org/v6/).
+
+</div>
+
+---
+
+## Why sally-defi-ts-sdk
+
+Most TypeScript DeFi code is raw `ethers`/`viem`: untyped tuples, hand-rolled
+approvals, a quote you *hope* matches execution, and zero protection against
+honeypots or sandwiches. sally-defi-ts-sdk collapses all of that into **one safe
+call**.
+
+`swap.execute` does the work a careful integrator would do by hand — approve →
+enumerate routes → **simulate every route on-chain** → screen the output token for
+honeypot/tax → set `minOut` from the *simulated* output → send → **assert you
+actually received it**. That whole pipeline is the default, not an opt-in.
+
+* 🌐 **Fully on-chain & decentralized.** Every read — prices, routes, positions,
+  balances — is a direct `eth_call` to the contracts. **No proprietary API, no
+  subgraph / Graph Node, no backend.** Point it at any RPC (or your own node) and
+  the only thing you trust is the chain itself.
+* 🎯 **Exact output, not an estimate.** Routes are ranked and `minOut` is set from
+  the realized `amountOut` of the *real* `executeHybridSwap` (`eth_call`'d against
+  live state), not a reserve-formula guess — `plan.simulatedOut` is what you'd
+  actually receive. See [docs/safety.md](docs/safety.md).
+* 🛡️ **Safety in the hot path.** Simulate-before-execute + post-trade balance-delta
+  assertion — not just in your test suite.
+* 🧱 **Typed end-to-end.** `pos.liquidity`, `plan.isSafe`, `quote.estimatedAmountOut`
+  — classes, autocomplete, ships `.d.ts`. No `tuple[7]`.
+* 🤖 **AI-agent-ready by construction.** Every return serializes cleanly, so wiring
+  Sally into LLM tools is mechanical.
+* ⚡ **Async + MEV-protection + permit** are constructor/option arguments, not projects.
+* 🪶 **Light deps** (just `ethers`), Node ≥ 18, full TypeScript types.
+
+Honest about scope: Sally routes within **its own protocol** on **Base + BSC** — it
+is not a 100-source aggregator. Full, cited comparison (advantages *and* trade-offs)
+vs raw ethers.js / viem / Uniswap SDK / aggregator SDKs:
+**[docs/comparison.md](docs/comparison.md)**.
+
+### 🌐 Fully on-chain, fully decentralized
+
+The SDK talks to **the chain and nothing else**. Routing, pricing, positions,
+honeypot screening and balances are all read with plain `eth_call`s against the
+on-chain contracts — there is **no Sally API, no Graph Node / subgraph, no indexer
+and no backend service** in the data path. The only runtime dependency is `ethers`.
+Bring your own RPC or node and you trust nothing but the chain.
+
+## What you get
+
+* **One object, every function.** `SallyClient` exposes the whole protocol through
+  feature namespaces (`prices`, `swap`, `wallet`, `liquidity`, `fees`). Reads need
+  only an RPC; writes need a signer.
+* **Safe by default.** `swap.execute` enumerates routes, **integrity-checks** each so
+  funds can never enter a wrong pool, **simulates** every candidate on-chain, picks
+  the best realized output, runs a **honeypot/tax probe** on the output token, sets
+  `minOut` from the simulation, then **asserts the received balance actually grew**.
+* **Single source of truth.** All addresses + ABIs come from the bundled
+  `deployment.json` (addresses + ABIs only). Nothing hard-coded; drop in a new
+  deployment and the SDK follows.
+* **Proxy-fallback aware.** v2.0.2 serves Lens views through the swap proxy and
+  Sidecar views through the liq proxy — the SDK wires this for you.
+* **Typed returns.** Every struct is a class (`SwapPath`, `V3Position`, `Lock`,
+  `SwapPlan`, …) — `pos.liquidity`, not `pos[7]`.
+
+## Install
+
+```bash
+npm install sally-defi-ts-sdk ethers
+```
+
+Requires Node ≥ 18 and `ethers >= 6`.
+
+## Quickstart (read-only)
+
+```ts
+import { SallyClient, Base } from "sally-defi-ts-sdk";
+
+const sally = new SallyClient("base", "https://mainnet.base.org");
+
+(await sally.prices.usd(Base.USDC)).asFloat;          // 1.0  (display / spot-mid)
+(await sally.prices.usdImpact(Base.WETH)).asFloat;    // 1703.19  (execution-aware)
+
+const quote = await sally.swap.quote(Base.WETH, Base.USDC, 10n ** 18n);
+Number(quote.estimatedAmountOut) / 1e6;               // 1703.45 USDC
+```
+
+## Swapping — safe by default
+
+```ts
+const sally = new SallyClient("base", RPC, { privateKey: "0x…" }); // or SALLY_PRIVATE_KEY env
+
+// Inspect first: compares every route, simulates each, screens the output token.
+const plan = await sally.swap.plan(Base.WETH, Base.USDC, 10n ** 18n);
+plan.summary();            // 'SwapPlan(… out~1702924727 sim=1702924727 min=1694410103 impact=13bps steps=2 SAFE)'
+plan.isSafe;               // false if honeypot / excessive tax / >15% impact / bad route
+plan.candidates;           // every route considered, with simulated output
+
+// Execute: same vetting, then send + balance-delta assertion.
+const receipt = await sally.swap.execute(Base.WETH, Base.USDC, 10n ** 18n, { slippageBps: 50 });
+
+// Native ETH in — pass the NATIVE sentinel; value is attached for you.
+import { NATIVE } from "sally-defi-ts-sdk";
+await sally.swap.execute(NATIVE, Base.USDC, 10n ** 17n, { slippageBps: 50 });
+```
+
+What `execute` does, in order: approve (exact amount) → enumerate routes →
+integrity-check → simulate each on-chain → pick best realized output →
+honeypot/tax preflight → `minOut` from the simulation → send →
+**assert received ≥ minOut**. See [`docs/safety.md`](docs/safety.md).
+
+Tune the guard rails:
+
+```ts
+import { SafetyConfig } from "sally-defi-ts-sdk";
+const sally = new SallyClient("base", RPC, {
+  privateKey: "0x…",
+  safety: new SafetyConfig({ slippageBps: 30, taxBlockBps: 3000, priceImpactBlockBps: 1000 }),
+});
+```
+
+## Liquidity
+
+```ts
+await sally.liquidity.addV2(4, Base.WETH, Base.USDC, 10n ** 15n, 2_000_000n, { lockDays: 0 });
+
+await sally.liquidity.positionsV3(wallet, 0, 10);    // V3Position[]
+await sally.liquidity.locks(wallet);                 // Lock[]
+await sally.liquidity.claimableFees(npm, tokenId);   // ClaimableFees
+// addV3 / addV4 / addSlipstream, increase/decrease, removeV2,
+// lock/unlock, claimFeesV3/V4(+Locked), massClaimFees, harvestOp
+```
+
+## Referral system 💸
+
+Every swap and liquidity action takes a `referral` address. Pass yours and the
+protocol accrues referral fees to it; read and claim them anytime:
+
+```ts
+await sally.swap.execute(Base.WETH, Base.USDC, 10n ** 18n, { referral: "0xYourRef" });
+
+await sally.fees.totalReferralOwed("0xYourRef");        // total owed across tokens
+await sally.fees.referralTokens("0xYourRef");           // per-token breakdown (paged)
+await sally.fees.claimReferral([Base.USDC, Base.WETH]); // claim selected tokens
+```
+
+See [`docs/referrals.md`](docs/referrals.md).
+
+## Async · permit · private mempool
+
+```ts
+// Async (concurrent quoting + simulation)
+import { AsyncSallyClient } from "sally-defi-ts-sdk/aio";
+import { Base } from "sally-defi-ts-sdk";
+const sally = new AsyncSallyClient("base", RPC, { privateKey: "0x…" });
+await sally.swap.execute(Base.WETH, Base.USDC, 10n ** 18n, { slippageBps: 50 });
+
+// EIP-2612 permit instead of approve
+await sally.swap.execute(Base.USDC, Base.WETH, 10n ** 8n, { approval: "permit" });
+
+// Private mempool (MEV protection)
+import { PrivateRelays } from "sally-defi-ts-sdk";
+new SallyClient("base", RPC, { privateKey: "0x…", privateRpcUrl: PrivateRelays.FLASHBOTS_FAST });
+```
+
+Full guide: [`docs/advanced.md`](docs/advanced.md).
+
+## Sign with your own wallet 🔑
+
+Give a `privateKey`, a `mnemonic`, or **no key at all** — build a vetted, simulated,
+ABI-decoded *unsigned* transaction and sign it with your own ethers wallet:
+
+```ts
+// mnemonic seed phrase
+const sally = new SallyClient("base", RPC, { mnemonic: "word1 … word12", accountIndex: 0 });
+
+// external signing — the SDK never holds your key
+const ext = new SallyClient("base", RPC, { address: "0xYourWallet" }); // knows sender, no key
+const build = await ext.swap.execute(Base.WETH, Base.USDC, 10n ** 18n, { buildOnly: true });
+build.plan.summary();       // what happens to your wallet: out, min, impact, safe?
+build.needsApproval;        // sign build.approveTx first if true
+build.swapTx;               // unsigned tx → sign with your own account, then broadcast
+
+// preview ANY call: decoded function + args + simulated result + revert reason
+(await ext.preview(fn, args)).summary();
+```
+
+See [`docs/signing.md`](docs/signing.md).
+
+## Namespaces
+
+| Namespace | What it covers |
+|---|---|
+| `client.prices` | `usd` (display), `usdImpact` (exec), `spot`, `weth`, `usdLiquidity`, `tokenInfo` |
+| `client.swap` | `quote(V2/V3/V4/Deep)`, `candidates`, `plan`, `simulateRoute`, `execute` (+ `buildOnly`), `tokenInfo` |
+| `client.wallet` | `balances`, `balancesRaw`, `totalUsd` |
+| `client.liquidity` | add / increase / decrease / remove / lock / claim / harvest, positions, pool state, dex registry |
+| `client.fees` | referral + batch fee reads & claims, `swapFee` |
+
+Raw contracts are always reachable: `client.swapContract`, `…liquidityContract`,
+`…lensContract`, `…sidecarContract`.
+
+## AI agents
+
+Every call returns a JSON-able typed object with a clear doc comment — wrapping Sally
+as LLM tools is trivial. See [`docs/ai-agents.md`](docs/ai-agents.md) and
+[`examples/10_ai_agent_tools.ts`](examples/10_ai_agent_tools.ts).
+
+## Docs
+
+| | |
+|---|---|
+| [Why sally-defi-ts-sdk](docs/comparison.md) | comparison vs other DeFi SDKs, advantages & trade-offs |
+| [Getting started](docs/getting-started.md) | install, connect, first read & swap |
+| [Swap & safety](docs/safety.md) | route comparison, simulation, all guard rails |
+| [Liquidity](docs/liquidity.md) | add/remove/lock/harvest across V2·V3·V4 |
+| [Pricing](docs/pricing.md) | display vs execution price, spot, impact |
+| [Referrals](docs/referrals.md) | earn & claim referral fees |
+| [Advanced](docs/advanced.md) | async client, EIP-2612 permit, Permit2, private mempool, BSC |
+| [AI agents](docs/ai-agents.md) | typed returns as tool functions |
+| [API reference](docs/api-reference.md) | every namespace + method |
+
+## Live deployment (v2.0.2, Base = BSC)
+
+| Contract | Address |
+|---|---|
+| SwapController (proxy) | `0x7777D0e2e2d772b5D750540B3932261574e87777` |
+| LiquidityController (proxy) | `0x7777d7fFF155B043CE0A0785dd8c8c42bEbe7777` |
+| Treasury | `0x7777D7dC7ea65F33EC126165e03C6B6030887777` |
+
+## Development & tests
+
+```bash
+npm install
+npm run build               # tsc -> dist/ (+ copies deployment.json)
+npm test                    # offline vitest unit tests (no network)
+npm run typecheck           # tsc --noEmit
+```
+
+## Support
+
+Questions, integrations, partnerships → [`support@sally.tools`](mailto:support@sally.tools)
+· [sally.tools](https://sally.tools)
+
+## License
+
+MIT

package/dist/aio/client.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Async entry point: {@link AsyncSallyClient}.
+ *
+ * Mirrors {@link SallyClient} on top of ethers' provider for non-blocking I/O.
+ * Shares all pure machinery (deployment, types, safety, errors, permit signing)
+ * with the sync client; only the network calls are awaited.
+ *
+ * In JS every network call is already async, so this client mainly differs from
+ * the main one in that its candidate quoting/simulation fans out concurrently
+ * (`Promise.all`), exactly like the Python `aio` client uses `asyncio.gather`.
+ *
+ * ```ts
+ * import { AsyncSallyClient } from "sally-defi-ts-sdk/aio";
+ * import { Base } from "sally-defi-ts-sdk";
+ *
+ * const sally = new AsyncSallyClient("base", RPC, { privateKey: "0x…" });
+ * console.log((await sally.prices.usd(Base.USDC)).asFloat);
+ * await sally.swap.execute(Base.WETH, Base.USDC, 10n ** 17n, { slippageBps: 50 });
+ * ```
+ */
+import { Contract, JsonRpcProvider, type Signer } from "ethers";
+import { SafetyConfig } from "../safety.js";
+import { AsyncToken } from "./token.js";
+import { AsyncPrices } from "./modules/prices.js";
+import { AsyncSwap } from "./modules/swap.js";
+import { AsyncWallet } from "./modules/wallet.js";
+import { AsyncLiquidity } from "./modules/liquidity.js";
+import { AsyncFees } from "./modules/fees.js";
+export interface AsyncSallyClientOptions {
+    privateKey?: string | null;
+    mnemonic?: string | null;
+    accountIndex?: number;
+    account?: Signer | null;
+    address?: string | null;
+    poa?: boolean | null;
+    safety?: SafetyConfig | null;
+    privateRpcUrl?: string | null;
+    gasMultiplier?: number;
+}
+type Fn = any;
+export declare class AsyncSallyClient {
+    readonly chainKey: string;
+    readonly chainId: number;
+    safety: SafetyConfig;
+    privateRpcUrl: string | null;
+    private _privateW3;
+    gasMultiplier: number;
+    w3: JsonRpcProvider;
+    account: Signer | null;
+    private _sender;
+    private _sendLock;
+    addresses: Record<string, string>;
+    private _cache;
+    constructor(chain?: string | number, rpcUrl?: string | null, opts?: AsyncSallyClientOptions);
+    isConnected(): Promise<boolean>;
+    get address(): string | null;
+    get canSign(): boolean;
+    requireAddress(): string;
+    requireSigner(): Signer;
+    private _contract;
+    private _cached;
+    get swapContract(): Contract;
+    get liquidityContract(): Contract;
+    get lensContract(): Contract;
+    get sidecarContract(): Contract;
+    token(address: string): AsyncToken;
+    call(fn: Fn, args?: any[], opts?: {
+        value?: bigint;
+        sender?: string | null;
+    }): Promise<any>;
+    buildTx(fn: Fn, args?: any[], opts?: {
+        value?: bigint;
+        gas?: bigint | null;
+    }): Promise<Record<string, any>>;
+    send(fn: Fn, args?: any[], opts?: {
+        value?: bigint;
+        gas?: bigint | null;
+        wait?: boolean;
+        simulate?: boolean;
+        private?: boolean | null;
+        timeout?: number;
+        buildOnly?: boolean;
+    }): Promise<any>;
+    private _broadcastPrivate;
+    get prices(): AsyncPrices;
+    get swap(): AsyncSwap;
+    get wallet(): AsyncWallet;
+    get liquidity(): AsyncLiquidity;
+    get fees(): AsyncFees;
+    toString(): string;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/aio/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/aio/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,QAAQ,EAER,eAAe,EAIf,KAAK,MAAM,EACZ,MAAM,QAAQ,CAAC;AAIhB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAkB9C,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,KAAK,EAAE,GAAG,GAAG,CAAC;AAEd,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,UAAU,CAAgC;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,eAAe,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC9B,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,SAAS,CAAoB;IACrC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,CAAC,MAAM,CAA2B;gBAE7B,KAAK,GAAE,MAAM,GAAG,MAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,GAAE,uBAA4B;IAyCjG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,cAAc,IAAI,MAAM;IAOxB,aAAa,IAAI,MAAM;IAQvB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,OAAO;IAKf,IAAI,YAAY,IAAI,QAAQ,CAE3B;IACD,IAAI,iBAAiB,IAAI,QAAQ,CAEhC;IACD,IAAI,YAAY,IAAI,QAAQ,CAE3B;IACD,IAAI,eAAe,IAAI,QAAQ,CAE9B;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAK5B,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,GAAG,EAAO,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAYnG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,GAAG,EAAO,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IA0CnH,IAAI,CACR,EAAE,EAAE,EAAE,EACN,IAAI,GAAE,GAAG,EAAO,EAChB,IAAI,GAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,CAAC;KAChB,GACL,OAAO,CAAC,GAAG,CAAC;YA2CD,iBAAiB;IAc/B,IAAI,MAAM,IAAI,WAAW,CAExB;IACD,IAAI,IAAI,IAAI,SAAS,CAEpB;IACD,IAAI,MAAM,IAAI,WAAW,CAExB;IACD,IAAI,SAAS,IAAI,cAAc,CAE9B;IACD,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED,QAAQ,IAAI,MAAM;CAInB"}

package/dist/aio/client.js

@@ -0,0 +1,283 @@
+/**
+ * Async entry point: {@link AsyncSallyClient}.
+ *
+ * Mirrors {@link SallyClient} on top of ethers' provider for non-blocking I/O.
+ * Shares all pure machinery (deployment, types, safety, errors, permit signing)
+ * with the sync client; only the network calls are awaited.
+ *
+ * In JS every network call is already async, so this client mainly differs from
+ * the main one in that its candidate quoting/simulation fans out concurrently
+ * (`Promise.all`), exactly like the Python `aio` client uses `asyncio.gather`.
+ *
+ * ```ts
+ * import { AsyncSallyClient } from "sally-defi-ts-sdk/aio";
+ * import { Base } from "sally-defi-ts-sdk";
+ *
+ * const sally = new AsyncSallyClient("base", RPC, { privateKey: "0x…" });
+ * console.log((await sally.prices.usd(Base.USDC)).asFloat);
+ * await sally.swap.execute(Base.WETH, Base.USDC, 10n ** 17n, { slippageBps: 50 });
+ * ```
+ */
+import { Contract, HDNodeWallet, JsonRpcProvider, Network, Wallet, getAddress, } from "ethers";
+import * as deployment from "../deployment.js";
+import { SallyConfigError, SallyError, SallyRevert, wrapWeb3Error } from "../errors.js";
+import { SafetyConfig } from "../safety.js";
+import { AsyncToken } from "./token.js";
+import { AsyncPrices } from "./modules/prices.js";
+import { AsyncSwap } from "./modules/swap.js";
+import { AsyncWallet } from "./modules/wallet.js";
+import { AsyncLiquidity } from "./modules/liquidity.js";
+import { AsyncFees } from "./modules/fees.js";
+/** Minimal async mutex: serialize an async critical section. */
+class AsyncMutex {
+    _chain = Promise.resolve();
+    async run(fn) {
+        const prev = this._chain;
+        let release;
+        this._chain = new Promise((res) => (release = res));
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+}
+export class AsyncSallyClient {
+    chainKey;
+    chainId;
+    safety;
+    privateRpcUrl;
+    _privateW3 = null;
+    gasMultiplier;
+    w3;
+    account = null;
+    _sender = null;
+    _sendLock = new AsyncMutex();
+    addresses;
+    _cache = {};
+    constructor(chain = "base", rpcUrl, opts = {}) {
+        this.chainKey = deployment.normalizeChain(chain);
+        this.chainId = deployment.chainId(this.chainKey);
+        this.safety = opts.safety ?? new SafetyConfig();
+        this.privateRpcUrl = opts.privateRpcUrl ?? process.env.SALLY_PRIVATE_RPC_URL ?? null;
+        this.gasMultiplier = opts.gasMultiplier ?? 1.25;
+        rpcUrl = rpcUrl ?? process.env.SALLY_RPC_URL ?? null;
+        if (!rpcUrl) {
+            throw new SallyConfigError("No rpcUrl given and SALLY_RPC_URL is unset.");
+        }
+        const network = Network.from(this.chainId);
+        this.w3 = new JsonRpcProvider(rpcUrl, network, { staticNetwork: network });
+        void (opts.poa ?? this.chainKey === "bsc");
+        const key = opts.privateKey ?? process.env.SALLY_PRIVATE_KEY ?? null;
+        const phrase = opts.mnemonic ?? process.env.SALLY_MNEMONIC ?? null;
+        if (opts.account != null) {
+            this.account = opts.account;
+        }
+        else if (key) {
+            this.account = new Wallet(key);
+        }
+        else if (phrase) {
+            const idx = opts.accountIndex ?? 0;
+            this.account = HDNodeWallet.fromPhrase(phrase, undefined, `m/44'/60'/0'/0/${idx}`);
+        }
+        this._sender = this.account
+            ? getAddress(this.account.address)
+            : opts.address
+                ? getAddress(opts.address)
+                : null;
+        this.addresses = Object.fromEntries(Object.entries(deployment.addresses(this.chainKey)).map(([k, v]) => [
+            k,
+            v.startsWith("0x") ? getAddress(v) : v,
+        ]));
+    }
+    // -- identity ---------------------------------------------------------- //
+    async isConnected() {
+        try {
+            await this.w3.getBlockNumber();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    get address() {
+        return this._sender;
+    }
+    get canSign() {
+        return this.account !== null;
+    }
+    requireAddress() {
+        if (!this._sender) {
+            throw new SallyConfigError("This action needs a sender (privateKey=…, mnemonic=…, or address='0x…').");
+        }
+        return this._sender;
+    }
+    requireSigner() {
+        if (this.account === null) {
+            throw new SallyConfigError("This action signs a tx and needs a key (privateKey=… or mnemonic=…).");
+        }
+        return this.account;
+    }
+    // -- contracts --------------------------------------------------------- //
+    _contract(address, component) {
+        return new Contract(getAddress(address), deployment.abi(this.chainKey, component), this.w3);
+    }
+    _cached(key, make) {
+        if (!(key in this._cache))
+            this._cache[key] = make();
+        return this._cache[key];
+    }
+    get swapContract() {
+        return this._cached("swapContract", () => this._contract(this.addresses["swap"], "swap"));
+    }
+    get liquidityContract() {
+        return this._cached("liquidityContract", () => this._contract(this.addresses["liquidity"], "liquidity"));
+    }
+    get lensContract() {
+        return this._cached("lensContract", () => this._contract(this.addresses["lens"], "lens"));
+    }
+    get sidecarContract() {
+        return this._cached("sidecarContract", () => this._contract(this.addresses["sidecar"], "sidecar"));
+    }
+    token(address) {
+        return new AsyncToken(this, address);
+    }
+    // -- call / send ------------------------------------------------------- //
+    async call(fn, args = [], opts = {}) {
+        const overrides = {};
+        if (opts.value)
+            overrides.value = opts.value;
+        const sender = opts.sender ?? this.address;
+        if (sender)
+            overrides.from = sender;
+        try {
+            return await fn.staticCall(...args, overrides);
+        }
+        catch (exc) {
+            throw wrapWeb3Error(this.chainKey, exc);
+        }
+    }
+    async buildTx(fn, args = [], opts = {}) {
+        const sender = this.requireAddress();
+        const overrides = { from: sender };
+        if (opts.value)
+            overrides.value = opts.value;
+        let tx;
+        try {
+            tx = { ...(await fn.populateTransaction(...args, overrides)) };
+        }
+        catch (exc) {
+            throw wrapWeb3Error(this.chainKey, exc);
+        }
+        tx.nonce = await this.w3.getTransactionCount(sender, "pending");
+        tx.chainId = this.chainId;
+        if (opts.value)
+            tx.value = opts.value;
+        const latest = await this.w3.getBlock("latest");
+        const feeData = await this.w3.getFeeData();
+        if (latest && latest.baseFeePerGas != null) {
+            let tip = feeData.maxPriorityFeePerGas;
+            if (tip == null)
+                tip = 1000000000n;
+            tx.maxPriorityFeePerGas = tip;
+            tx.maxFeePerGas = tip + 2n * latest.baseFeePerGas;
+            tx.type = 2;
+            delete tx.gasPrice;
+        }
+        else {
+            tx.gasPrice = feeData.gasPrice ?? 0n;
+            tx.type = 0;
+        }
+        let gas = opts.gas ?? null;
+        if (gas !== null) {
+            tx.gasLimit = gas;
+        }
+        else {
+            const overrides2 = { from: sender };
+            if (opts.value)
+                overrides2.value = opts.value;
+            let est = BigInt(await fn.estimateGas(...args, overrides2));
+            if (this.gasMultiplier && this.gasMultiplier !== 1.0) {
+                est = (est * BigInt(Math.round(this.gasMultiplier * 1000))) / 1000n;
+            }
+            tx.gasLimit = est;
+        }
+        delete tx.gas;
+        return tx;
+    }
+    async send(fn, args = [], opts = {}) {
+        const value = opts.value ?? 0n;
+        const wait = opts.wait ?? true;
+        const simulate = opts.simulate ?? true;
+        const timeout = opts.timeout ?? 180;
+        if (simulate) {
+            await this.call(fn, args, { value, sender: this.address });
+        }
+        if (opts.buildOnly) {
+            return this.buildTx(fn, args, { value, gas: opts.gas ?? null });
+        }
+        const account = this.requireSigner();
+        const usePrivate = opts.private == null ? this.privateRpcUrl !== null : opts.private;
+        const txh = await this._sendLock.run(async () => {
+            const tx = await this.buildTx(fn, args, { value, gas: opts.gas ?? null });
+            const raw = await account.signTransaction(tx);
+            if (usePrivate)
+                return this._broadcastPrivate(raw);
+            const resp = await this.w3.broadcastTransaction(raw);
+            return resp.hash;
+        });
+        if (!wait)
+            return txh;
+        let receipt;
+        try {
+            receipt = await this.w3.waitForTransaction(txh, 1, timeout * 1000);
+        }
+        catch {
+            receipt = null;
+        }
+        if (receipt === null) {
+            const where = usePrivate ? "private relay" : "public mempool";
+            throw new SallyError(`tx ${txh} not mined within ${timeout}s via ${where}. It may have been ` +
+                `dropped/not included — check the hash before resubmitting.`);
+        }
+        if (receipt.status !== 1) {
+            throw new SallyRevert("Error", [], null, `tx ${txh} reverted on-chain`);
+        }
+        return receipt;
+    }
+    async _broadcastPrivate(rawTx) {
+        if (!this.privateRpcUrl) {
+            throw new SallyConfigError("private=true but no privateRpcUrl configured.");
+        }
+        if (this._privateW3 === null) {
+            this._privateW3 = new JsonRpcProvider(this.privateRpcUrl, Network.from(this.chainId), {
+                staticNetwork: Network.from(this.chainId),
+            });
+        }
+        const resp = await this._privateW3.broadcastTransaction(rawTx);
+        return resp.hash;
+    }
+    // -- namespaces -------------------------------------------------------- //
+    get prices() {
+        return this._cached("prices", () => new AsyncPrices(this));
+    }
+    get swap() {
+        return this._cached("swap", () => new AsyncSwap(this));
+    }
+    get wallet() {
+        return this._cached("wallet", () => new AsyncWallet(this));
+    }
+    get liquidity() {
+        return this._cached("liquidity", () => new AsyncLiquidity(this));
+    }
+    get fees() {
+        return this._cached("fees", () => new AsyncFees(this));
+    }
+    toString() {
+        const who = this.address ?? "read-only";
+        return `<AsyncSallyClient chain=${this.chainKey} id=${this.chainId} signer=${who}>`;
+    }
+}
+//# sourceMappingURL=client.js.map