@bananapus/nana-sdk-core 1.5.0 → 1.6.0

package/dist/cjs/v6/launch.js

@@ -30,17 +30,19 @@ async function getProjectCreationFee(client, chainId) {
 /**
  * Build a `JBAccountingContext` for a token.
  *
- * The context currency is ALWAYS token-keyed: `uint32(uint160(token))`
- * (native token → 61166). This is distinct from a ruleset's `baseCurrency`,
- * which must be a standard currency id (ETH=1, USD=2) — never use a
- * token-keyed currency as a base currency to "skip the price feed".
+ * By default the context currency is token-keyed: `uint32(uint160(token))`
+ * (native token → 61166). Pass an explicit shared currency such as ETH=1 or
+ * USD=2 when the terminal should convert this token through a protocol price
+ * feed. A ruleset's `baseCurrency` is the denomination used to interpret its
+ * issuance weight.
  *
  * @param token The token address. Defaults to the native token sentinel
  * (`0x…EEEe`).
  * @param decimals The token's decimals. Defaults to 18 for the native token;
  * REQUIRED for any other token (there is no safe default).
+ * @param currency The context's currency id. Defaults to the token-keyed id.
  */
-function buildAccountingContext(token = constants_js_1.NATIVE_TOKEN, decimals) {
+function buildAccountingContext(token = constants_js_1.NATIVE_TOKEN, decimals, currency = (0, currency_js_1.tokenCurrencyId)(token)) {
     const isNative = token.toLowerCase() === constants_js_1.NATIVE_TOKEN.toLowerCase();
     if (decimals === undefined && !isNative) {
         throw new Error(`decimals is required for non-native token ${token} (there is no safe default)`);
@@ -48,7 +50,7 @@ function buildAccountingContext(token = constants_js_1.NATIVE_TOKEN, decimals) {
     return {
         token,
         decimals: decimals ?? constants_js_1.NATIVE_TOKEN_DECIMALS,
-        currency: (0, currency_js_1.tokenCurrencyId)(token),
+        currency,
     };
 }
 /**

package/dist/cjs/v6/launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../../src/v6/launch.ts"],"names":[],"mappings":";;AA2CA,sDASC;AAeD,wDAeC;AAcD,kEAsBC;AAYD,oDAyBC;AAsBD,8DAoBC;AAoBD,oDAuBC;AAgBD,sDAsBC;AAGD,0DASC;AAlSD,+BAQc;AACd,kDAAsE;AACtE,0DAA0E;AAE1E,+CAAmE;AAGnE,yCAAuC;AAqBvC;;;;;;GAMG;AACI,KAAK,UAAU,qBAAqB,CACzC,MAAoB,EACpB,OAAkB;IAElB,OAAO,MAAM,CAAC,YAAY,CAAC;QACzB,OAAO,EAAE,IAAA,oBAAS,EAAC,YAAY,EAAE,OAAO,CAAC;QACzC,GAAG,EAAE,2BAAa;QAClB,YAAY,EAAE,aAAa;KAC5B,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,sBAAsB,CACpC,QAAiB,2BAAY,EAC7B,QAAiB;IAEjB,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,EAAE,KAAK,2BAAY,CAAC,WAAW,EAAE,CAAC;IACpE,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,6CAA6C,KAAK,6BAA6B,CAChF,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK;QACL,QAAQ,EAAE,QAAQ,IAAI,oCAAqB;QAC3C,QAAQ,EAAE,IAAA,6BAAe,EAAC,KAAK,CAAC;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,2BAA2B,CAAC,IAG3C;IACC,MAAM,cAAc,GAAuB;QACzC;YACE,QAAQ,EAAE,IAAA,oBAAS,EAAC,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC;YACpD,0BAA0B,EAAE,IAAI,CAAC,kBAAkB,IAAI;gBACrD,sBAAsB,EAAE;aACzB;SACF;KACF,CAAC;IACF,IAAI,CAAC;QACH,cAAc,CAAC,IAAI,CAAC;YAClB,QAAQ,EAAE,IAAA,oBAAS,EAAC,0BAA0B,EAAE,IAAI,CAAC,OAAO,CAAC;YAC7D,0BAA0B,EAAE,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,4BAA4B;IAC9B,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,oBAAoB,CAClC,SAAsC;IAEtC,OAAO;QACL,eAAe,EAAE,CAAC;QAClB,cAAc,EAAE,CAAC;QACjB,YAAY,EAAE,+BAAiB;QAC/B,QAAQ,EAAE,KAAK;QACf,oBAAoB,EAAE,KAAK;QAC3B,iBAAiB,EAAE,KAAK;QACxB,mBAAmB,EAAE,KAAK;QAC1B,sBAAsB,EAAE,KAAK;QAC7B,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,KAAK;QACzB,yBAAyB,EAAE,KAAK;QAChC,iBAAiB,EAAE,KAAK;QACxB,oBAAoB,EAAE,KAAK;QAC3B,QAAQ,EAAE,KAAK;QACf,4BAA4B,EAAE,KAAK;QACnC,iBAAiB,EAAE,KAAK;QACxB,qBAAqB,EAAE,KAAK;QAC5B,QAAQ,EAAE,kBAAW;QACrB,QAAQ,EAAE,CAAC;QACX,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,yBAAyB,CAAC,IASzC;IACC,OAAO;QACL,kBAAkB,EAAE,IAAI,EAAE,kBAAkB,IAAI,CAAC;QACjD,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,CAAC;QAC7B,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,EAAE;QAC1B,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,IAAI,CAAC;QAC7C,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,kBAAW;QAC/C,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,oBAAoB,EAAE;QAClD,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,EAAE;QACpC,qBAAqB,EAAE,IAAI,EAAE,qBAAqB,IAAI,EAAE;KACzD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,oBAAoB,CAAC,IAQpC;IACC,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,IAAA,oBAAS,EAAC,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC;QAChD,GAAG,EAAE,6BAAe;QACpB,YAAY,EAAE,kBAA2B;QACzC,IAAI,EAAE;YACJ,IAAI,CAAC,KAAK;YACV,IAAI,CAAC,UAAU;YACf,IAAI,CAAC,qBAAqB;YAC1B,IAAI,CAAC,sBAAsB;YAC3B,IAAI,CAAC,IAAI,IAAI,EAAE;SACP;QACV,KAAK,EAAE,IAAI,CAAC,WAAW;KACxB,CAAC;AACJ,CAAC;AASD;;;;;;GAMG;AACH,SAAgB,qBAAqB,CACnC,GAAuB,EACvB,EAAE,OAAO,EAA0B;IAEnC,IAAI,CAAC,IAAA,qBAAc,EAAC,GAAG,CAAC,OAAO,EAAE,IAAA,oBAAS,EAAC,cAAc,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;QACrE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAA,qBAAc,EAAC;YAC7B,GAAG,EAAE,6BAAe;YACpB,SAAS,EAAE,eAAe;YAC1B,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,GAAG,CAAC,MAAyB;YACrC,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,SAAS,KAAK,eAAe;YAC1C,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS;YACxB,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,SAAgB,uBAAuB,CACrC,IAAmC,EACnC,IAA4B;IAE5B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,qBAAqB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACnD,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../../src/v6/launch.ts"],"names":[],"mappings":"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"}

package/dist/cjs/v6/revnets.d.ts

@@ -8,8 +8,8 @@ type RevDeployArgs4 = Extract<RevDeployArgs, readonly [unknown, unknown, unknown
 /**
  * A revnet's full configuration: its token description (name/ticker/uri and
  * the salt that fixes the ERC-20's deterministic address), base currency
- * (ETH=1 or USD=2 — a standard `JBCurrencyIds` id, never a token-keyed
- * currency), operator, and stage configurations.
+ * (either a token-keyed currency or a well-known `JBCurrencyIds` id such as
+ * ETH=1 or USD=2), operator, and stage configurations.
  */
 export type REVConfig = RevDeployArgs4[1];
 /**

package/dist/esm/v6/cashOut.d.ts

@@ -108,4 +108,191 @@ export declare function getCashOutQuote(client: PublicClient, { chainId, project
     decimals?: bigint;
     currency?: bigint;
 }): Promise<CashOutQuote>;
+/**
+ * The default cash-out slippage tolerance, in basis points (1%).
+ *
+ * Quotes from {@link getHookAwareCashOutQuote} are exact against current state;
+ * this tolerance only absorbs quote-to-inclusion drift (payments, other cash
+ * outs, sucker snapshot syncs, or pool moves that land first).
+ */
+export declare const DEFAULT_CASH_OUT_SLIPPAGE_BPS = 100n;
+/**
+ * Apply a slippage tolerance to a quoted output, flooring toward zero but
+ * never below 1 for a positive quote (a zero minimum disables protection).
+ *
+ * @param quoted The quoted output amount.
+ * @param slippageBps The tolerance in basis points. Defaults to
+ * {@link DEFAULT_CASH_OUT_SLIPPAGE_BPS}.
+ * @returns The minimum acceptable output.
+ */
+export declare function slippageFloor(quoted: bigint, slippageBps?: bigint): bigint;
+/**
+ * The exact protocol fee `JBMultiTerminal` deducts from a cash-out reclaim:
+ * `reclaimAmount / 40` (2.5%, floor division — NOT `× 975 / 1000`, which can
+ * differ by 1 wei and break an exact minimum).
+ *
+ * With a non-zero cash-out tax rate the fee applies to the full reclaim. With
+ * a zero tax rate it applies only up to the project's fee-free surplus
+ * (round-trip prevention). Feeless beneficiaries pay no fee.
+ *
+ * @param args.reclaimAmount The gross reclaim amount, before the terminal fee.
+ * @param args.cashOutTaxRate The ruleset's cash-out tax rate.
+ * @param args.beneficiaryIsFeeless Whether the beneficiary is feeless.
+ * @param args.feeFreeSurplus The project's `feeFreeSurplusOf` counter for the
+ * reclaimed token. Only consulted when the tax rate is zero.
+ * @returns The fee amount the terminal will deduct.
+ */
+export declare function cashOutProtocolFee({ reclaimAmount, cashOutTaxRate, beneficiaryIsFeeless, feeFreeSurplus, }: {
+    reclaimAmount: bigint;
+    cashOutTaxRate: bigint;
+    beneficiaryIsFeeless?: boolean;
+    feeFreeSurplus?: bigint;
+}): bigint;
+/**
+ * The diagnostic payload the buyback hook packs into its cash-out hook
+ * specification — the protocol's public preview API for the sell-side routing
+ * decision (returned by `previewCashOutFrom` whether or not the pool route
+ * wins).
+ */
+export interface BuybackCashOutSpec {
+    minimumSwapAmountOut: bigint;
+    cashOutCountToSell: bigint;
+    netDirectCashOutAmount: bigint;
+    twapTick: number;
+    twapLiquidity: bigint;
+    poolId: Hex;
+    rawSwapQuote: bigint;
+    hasUserSpecifiedMinimumSwapAmountOut: boolean;
+}
+/**
+ * Decode the buyback hook's cash-out specification metadata (see
+ * {@link BuybackCashOutSpec}).
+ */
+export declare function decodeBuybackCashOutSpec(metadata: Hex): BuybackCashOutSpec;
+/**
+ * Build the buyback hook's `cashOut` metadata entry:
+ * `(uint256 minimumSwapAmountOut, bool skip)`.
+ *
+ * `minimumSwapAmountOut` is a hard floor on the net terminal-token output,
+ * enforced by the hook on BOTH the pool route and the direct bonding-curve
+ * fallback. Note an explicit non-zero minimum skips the hook's TWAP lookup:
+ * a minimum at or below the direct net keeps execution on the terminal path,
+ * a minimum above it routes through the pool. `skip: true` forces the
+ * terminal path outright (the floor still applies).
+ *
+ * @param args.hook The hook address the terminal consults (from the preview's
+ * hook specification).
+ * @param args.minimumSwapAmountOut The net-output floor.
+ * @param args.skip Force the direct terminal path. Defaults to false.
+ * @returns The metadata to pass as `cashOutTokensOf`'s `metadata` argument.
+ */
+export declare function buildBuybackCashOutMetadata({ hook, minimumSwapAmountOut, skip, }: {
+    hook: Address;
+    minimumSwapAmountOut: bigint;
+    skip?: boolean;
+}): Hex;
+/** A hook specification tuple as returned by the terminal preview functions. */
+export interface CashOutHookSpecification {
+    hook: Address;
+    noop: boolean;
+    amount: bigint;
+    metadata: Hex;
+}
+/**
+ * A slippage-protected cash-out route: which venue the transaction should
+ * expect, and the exact `minTokensReclaimed`/`metadata` pair to submit.
+ */
+export interface CashOutRoute {
+    /** "treasury" = direct bonding-curve reclaim; "amm" = buyback pool sell. */
+    route: "treasury" | "amm";
+    /** The quoted net output on the chosen route. */
+    expectedReturn: bigint;
+    /** The slippage-floored minimum net output. */
+    minimumReturn: bigint;
+    /**
+     * The `minTokensReclaimed` to pass to `cashOutTokensOf`. Non-zero only on
+     * the treasury route — on the pool route the terminal itself reclaims
+     * nothing (the hook pays the beneficiary), so the floor lives in
+     * {@link CashOutRoute.metadata} instead.
+     */
+    terminalMinimum: bigint;
+    /** The `metadata` to pass to `cashOutTokensOf`. */
+    metadata: Hex;
+    /** The gross direct reclaim, before the terminal fee. */
+    treasuryGross: bigint;
+    /** The terminal fee on the direct reclaim. */
+    treasuryProtocolFee: bigint;
+    /** The net direct reclaim after the terminal fee. */
+    treasuryNet: bigint;
+    /** The decoded buyback diagnostics, when the hook was consulted. */
+    buyback: (BuybackCashOutSpec & {
+        hook: Address;
+    }) | null;
+}
+/**
+ * Interpret a hook-aware `previewCashOutFrom` result and prepare a
+ * slippage-protected route.
+ *
+ * On the treasury route the floor is enforced via `minTokensReclaimed`; if the
+ * routing flips to the pool between quote and inclusion, the transaction
+ * reverts rather than executing a stale path — re-quote and retry. On the pool
+ * route the floor is moved into the hook's `cashOut` metadata (the terminal
+ * minimum must be zero there), and if the floored pool quote no longer beats
+ * the direct net, the route falls back to the treasury path.
+ *
+ * @param args.reclaimAmount `previewCashOutFrom`'s gross reclaim amount.
+ * @param args.cashOutTaxRate `previewCashOutFrom`'s cash-out tax rate.
+ * @param args.hookSpecifications `previewCashOutFrom`'s hook specifications.
+ * @param args.beneficiaryIsFeeless Whether the beneficiary is feeless.
+ * Defaults to false (conservative: assumes the fee applies).
+ * @param args.feeFreeSurplus The terminal's `feeFreeSurplusOf` for the token.
+ * Only consulted when the tax rate is zero. Defaults to 0.
+ * @param args.slippageBps Tolerance for quote-to-inclusion drift. Defaults to
+ * {@link DEFAULT_CASH_OUT_SLIPPAGE_BPS}.
+ * @returns The protected route.
+ */
+export declare function resolveCashOutRoute({ reclaimAmount, cashOutTaxRate, hookSpecifications, beneficiaryIsFeeless, feeFreeSurplus, slippageBps, }: {
+    reclaimAmount: bigint;
+    cashOutTaxRate: bigint;
+    hookSpecifications: readonly CashOutHookSpecification[];
+    beneficiaryIsFeeless?: boolean;
+    feeFreeSurplus?: bigint;
+    slippageBps?: bigint;
+}): CashOutRoute;
+/**
+ * Quote a cash out through `JBMultiTerminal.previewCashOutFrom` — the
+ * hook-aware simulation of the REAL cash-out path (data hook, buyback
+ * routing, cross-chain terms) — and prepare a slippage-protected route.
+ *
+ * Prefer this over {@link getCashOutQuote} for building transactions:
+ * `currentReclaimableSurplusOf` skips the data hook entirely, so its result
+ * can diverge from what `cashOutTokensOf` pays and is unsafe to use as a
+ * minimum.
+ *
+ * @param client A viem public client on the given chain.
+ * @param args.chainId The chain to quote on.
+ * @param args.projectId The project's id.
+ * @param args.holder The address whose tokens would be cashed out.
+ * @param args.cashOutCount The number of project tokens to cash out.
+ * @param args.tokenToReclaim The terminal token to reclaim.
+ * @param args.beneficiary The reclaim beneficiary. Defaults to the holder.
+ * @param args.terminal The terminal to quote against. Defaults to the chain's
+ * canonical `JBMultiTerminal`.
+ * @param args.beneficiaryIsFeeless Whether the beneficiary is feeless.
+ * Defaults to false.
+ * @param args.slippageBps Tolerance for quote-to-inclusion drift. Defaults to
+ * {@link DEFAULT_CASH_OUT_SLIPPAGE_BPS}.
+ * @returns The protected route (see {@link CashOutRoute}).
+ */
+export declare function getHookAwareCashOutQuote(client: PublicClient, { chainId, projectId, holder, cashOutCount, tokenToReclaim, beneficiary, terminal, beneficiaryIsFeeless, slippageBps, }: {
+    chainId: JBChainId;
+    projectId: bigint;
+    holder: Address;
+    cashOutCount: bigint;
+    tokenToReclaim: Address;
+    beneficiary?: Address;
+    terminal?: Address;
+    beneficiaryIsFeeless?: boolean;
+    slippageBps?: bigint;
+}): Promise<CashOutRoute>;
 //# sourceMappingURL=cashOut.d.ts.map

package/dist/esm/v6/cashOut.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cashOut.d.ts","sourceRoot":"","sources":["../../../src/v6/cashOut.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AACvE,OAAO,EACL,kBAAkB,EAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAMxC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,OAAO,kBAAkB,CAAC;IAC/B,YAAY,EAAE,iBAAiB,CAAC;IAChC,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,cAAc,EACd,kBAAuB,EACvB,WAAW,EACX,QAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB,GAAG,kBAAkB,CAgBrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,gBAAgB,EAChB,QAAQ,GACT,EAAE;IACD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GAAG,GAAG,CAiBN;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,EACE,OAAO,EACP,SAAS,EACT,YAAY,EACZ,QAAc,EACd,QAA2C,GAC5C,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,YAAY,CAAC,CAYvB"}
+{"version":3,"file":"cashOut.d.ts","sourceRoot":"","sources":["../../../src/v6/cashOut.ts"],"names":[],"mappings":"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"}

package/dist/esm/v6/cashOut.js

@@ -1,4 +1,4 @@
-import { encodeAbiParameters } from "viem";
+import { decodeAbiParameters, encodeAbiParameters, } from "viem";
 import { jbMultiTerminalAbi, jbTerminalStoreAbi, } from "../generated/juicebox.js";
 import { applyJbDaoCashOutFee } from "../utils/fee.js";
 import { createHookMetadata, hookMetadataId } from "../utils/hook.js";
@@ -104,4 +104,248 @@ export async function getCashOutQuote(client, { chainId, projectId, cashOutCount
         reclaimAmountAfterFee: applyJbDaoCashOutFee(reclaimAmount),
     };
 }
+/**
+ * The default cash-out slippage tolerance, in basis points (1%).
+ *
+ * Quotes from {@link getHookAwareCashOutQuote} are exact against current state;
+ * this tolerance only absorbs quote-to-inclusion drift (payments, other cash
+ * outs, sucker snapshot syncs, or pool moves that land first).
+ */
+export const DEFAULT_CASH_OUT_SLIPPAGE_BPS = 100n;
+const MAX_BPS = 10000n;
+function requireBps(slippageBps) {
+    if (slippageBps < 0n || slippageBps >= MAX_BPS) {
+        throw new Error("Slippage basis points must be in [0, 10000)");
+    }
+    return slippageBps;
+}
+/**
+ * Apply a slippage tolerance to a quoted output, flooring toward zero but
+ * never below 1 for a positive quote (a zero minimum disables protection).
+ *
+ * @param quoted The quoted output amount.
+ * @param slippageBps The tolerance in basis points. Defaults to
+ * {@link DEFAULT_CASH_OUT_SLIPPAGE_BPS}.
+ * @returns The minimum acceptable output.
+ */
+export function slippageFloor(quoted, slippageBps = DEFAULT_CASH_OUT_SLIPPAGE_BPS) {
+    requireBps(slippageBps);
+    if (quoted <= 0n)
+        return 0n;
+    const floor = (quoted * (MAX_BPS - slippageBps)) / MAX_BPS;
+    return floor > 0n ? floor : 1n;
+}
+/**
+ * The exact protocol fee `JBMultiTerminal` deducts from a cash-out reclaim:
+ * `reclaimAmount / 40` (2.5%, floor division — NOT `× 975 / 1000`, which can
+ * differ by 1 wei and break an exact minimum).
+ *
+ * With a non-zero cash-out tax rate the fee applies to the full reclaim. With
+ * a zero tax rate it applies only up to the project's fee-free surplus
+ * (round-trip prevention). Feeless beneficiaries pay no fee.
+ *
+ * @param args.reclaimAmount The gross reclaim amount, before the terminal fee.
+ * @param args.cashOutTaxRate The ruleset's cash-out tax rate.
+ * @param args.beneficiaryIsFeeless Whether the beneficiary is feeless.
+ * @param args.feeFreeSurplus The project's `feeFreeSurplusOf` counter for the
+ * reclaimed token. Only consulted when the tax rate is zero.
+ * @returns The fee amount the terminal will deduct.
+ */
+export function cashOutProtocolFee({ reclaimAmount, cashOutTaxRate, beneficiaryIsFeeless = false, feeFreeSurplus = 0n, }) {
+    if (reclaimAmount <= 0n || beneficiaryIsFeeless)
+        return 0n;
+    if (cashOutTaxRate > 0n)
+        return reclaimAmount / 40n;
+    const feeable = reclaimAmount < feeFreeSurplus ? reclaimAmount : feeFreeSurplus;
+    return feeable / 40n;
+}
+const BUYBACK_CASH_OUT_SPEC_ABI = [
+    { name: "minimumSwapAmountOut", type: "uint256" },
+    { name: "cashOutCountToSell", type: "uint256" },
+    { name: "netDirectCashOutAmount", type: "uint256" },
+    { name: "twapTick", type: "int24" },
+    { name: "twapLiquidity", type: "uint128" },
+    { name: "poolId", type: "bytes32" },
+    { name: "rawSwapQuote", type: "uint256" },
+    { name: "hasUserSpecifiedMinimumSwapAmountOut", type: "bool" },
+];
+/**
+ * Decode the buyback hook's cash-out specification metadata (see
+ * {@link BuybackCashOutSpec}).
+ */
+export function decodeBuybackCashOutSpec(metadata) {
+    const [minimumSwapAmountOut, cashOutCountToSell, netDirectCashOutAmount, twapTick, twapLiquidity, poolId, rawSwapQuote, hasUserSpecifiedMinimumSwapAmountOut,] = decodeAbiParameters(BUYBACK_CASH_OUT_SPEC_ABI, metadata);
+    return {
+        minimumSwapAmountOut,
+        cashOutCountToSell,
+        netDirectCashOutAmount,
+        twapTick,
+        twapLiquidity,
+        poolId,
+        rawSwapQuote,
+        hasUserSpecifiedMinimumSwapAmountOut,
+    };
+}
+/**
+ * Build the buyback hook's `cashOut` metadata entry:
+ * `(uint256 minimumSwapAmountOut, bool skip)`.
+ *
+ * `minimumSwapAmountOut` is a hard floor on the net terminal-token output,
+ * enforced by the hook on BOTH the pool route and the direct bonding-curve
+ * fallback. Note an explicit non-zero minimum skips the hook's TWAP lookup:
+ * a minimum at or below the direct net keeps execution on the terminal path,
+ * a minimum above it routes through the pool. `skip: true` forces the
+ * terminal path outright (the floor still applies).
+ *
+ * @param args.hook The hook address the terminal consults (from the preview's
+ * hook specification).
+ * @param args.minimumSwapAmountOut The net-output floor.
+ * @param args.skip Force the direct terminal path. Defaults to false.
+ * @returns The metadata to pass as `cashOutTokensOf`'s `metadata` argument.
+ */
+export function buildBuybackCashOutMetadata({ hook, minimumSwapAmountOut, skip = false, }) {
+    if (minimumSwapAmountOut < 0n) {
+        throw new Error("Cash out minimum cannot be negative");
+    }
+    const payload = encodeAbiParameters([{ type: "uint256" }, { type: "bool" }], [minimumSwapAmountOut, skip]);
+    return createHookMetadata([hookMetadataId(hook, "cashOut")], [payload]);
+}
+/**
+ * Interpret a hook-aware `previewCashOutFrom` result and prepare a
+ * slippage-protected route.
+ *
+ * On the treasury route the floor is enforced via `minTokensReclaimed`; if the
+ * routing flips to the pool between quote and inclusion, the transaction
+ * reverts rather than executing a stale path — re-quote and retry. On the pool
+ * route the floor is moved into the hook's `cashOut` metadata (the terminal
+ * minimum must be zero there), and if the floored pool quote no longer beats
+ * the direct net, the route falls back to the treasury path.
+ *
+ * @param args.reclaimAmount `previewCashOutFrom`'s gross reclaim amount.
+ * @param args.cashOutTaxRate `previewCashOutFrom`'s cash-out tax rate.
+ * @param args.hookSpecifications `previewCashOutFrom`'s hook specifications.
+ * @param args.beneficiaryIsFeeless Whether the beneficiary is feeless.
+ * Defaults to false (conservative: assumes the fee applies).
+ * @param args.feeFreeSurplus The terminal's `feeFreeSurplusOf` for the token.
+ * Only consulted when the tax rate is zero. Defaults to 0.
+ * @param args.slippageBps Tolerance for quote-to-inclusion drift. Defaults to
+ * {@link DEFAULT_CASH_OUT_SLIPPAGE_BPS}.
+ * @returns The protected route.
+ */
+export function resolveCashOutRoute({ reclaimAmount, cashOutTaxRate, hookSpecifications, beneficiaryIsFeeless = false, feeFreeSurplus = 0n, slippageBps = DEFAULT_CASH_OUT_SLIPPAGE_BPS, }) {
+    requireBps(slippageBps);
+    const treasuryProtocolFee = cashOutProtocolFee({
+        reclaimAmount,
+        cashOutTaxRate,
+        beneficiaryIsFeeless,
+        feeFreeSurplus,
+    });
+    const treasuryNet = reclaimAmount - treasuryProtocolFee;
+    const specification = hookSpecifications.find((spec) => spec.metadata !== "0x") ?? null;
+    const buyback = specification
+        ? {
+            hook: specification.hook,
+            ...decodeBuybackCashOutSpec(specification.metadata),
+        }
+        : null;
+    const treasuryRoute = {
+        route: "treasury",
+        expectedReturn: treasuryNet,
+        minimumReturn: slippageFloor(treasuryNet, slippageBps),
+        terminalMinimum: slippageFloor(treasuryNet, slippageBps),
+        metadata: "0x",
+        treasuryGross: reclaimAmount,
+        treasuryProtocolFee,
+        treasuryNet,
+        buyback,
+    };
+    if (!specification || specification.noop || !buyback)
+        return treasuryRoute;
+    // The pool route won the preview. Re-previews with an explicit metadata
+    // minimum report that already-protected floor and no raw quote — preserve
+    // it instead of discounting a second time.
+    const quote = buyback.rawSwapQuote > 0n
+        ? buyback.rawSwapQuote
+        : buyback.minimumSwapAmountOut;
+    const minimumReturn = buyback.rawSwapQuote > 0n && !buyback.hasUserSpecifiedMinimumSwapAmountOut
+        ? slippageFloor(quote, slippageBps)
+        : buyback.minimumSwapAmountOut;
+    // An explicit metadata minimum at or below the direct net routes execution
+    // back to the terminal path anyway; take the deterministic treasury route.
+    if (quote <= 0n || minimumReturn <= buyback.netDirectCashOutAmount) {
+        return treasuryRoute;
+    }
+    return {
+        route: "amm",
+        expectedReturn: quote,
+        minimumReturn,
+        terminalMinimum: 0n,
+        metadata: buildBuybackCashOutMetadata({
+            hook: specification.hook,
+            minimumSwapAmountOut: minimumReturn,
+        }),
+        treasuryGross: reclaimAmount,
+        treasuryProtocolFee,
+        treasuryNet,
+        buyback,
+    };
+}
+/**
+ * Quote a cash out through `JBMultiTerminal.previewCashOutFrom` — the
+ * hook-aware simulation of the REAL cash-out path (data hook, buyback
+ * routing, cross-chain terms) — and prepare a slippage-protected route.
+ *
+ * Prefer this over {@link getCashOutQuote} for building transactions:
+ * `currentReclaimableSurplusOf` skips the data hook entirely, so its result
+ * can diverge from what `cashOutTokensOf` pays and is unsafe to use as a
+ * minimum.
+ *
+ * @param client A viem public client on the given chain.
+ * @param args.chainId The chain to quote on.
+ * @param args.projectId The project's id.
+ * @param args.holder The address whose tokens would be cashed out.
+ * @param args.cashOutCount The number of project tokens to cash out.
+ * @param args.tokenToReclaim The terminal token to reclaim.
+ * @param args.beneficiary The reclaim beneficiary. Defaults to the holder.
+ * @param args.terminal The terminal to quote against. Defaults to the chain's
+ * canonical `JBMultiTerminal`.
+ * @param args.beneficiaryIsFeeless Whether the beneficiary is feeless.
+ * Defaults to false.
+ * @param args.slippageBps Tolerance for quote-to-inclusion drift. Defaults to
+ * {@link DEFAULT_CASH_OUT_SLIPPAGE_BPS}.
+ * @returns The protected route (see {@link CashOutRoute}).
+ */
+export async function getHookAwareCashOutQuote(client, { chainId, projectId, holder, cashOutCount, tokenToReclaim, beneficiary, terminal, beneficiaryIsFeeless = false, slippageBps = DEFAULT_CASH_OUT_SLIPPAGE_BPS, }) {
+    const terminalAddress = terminal ?? v6Address("JBMultiTerminal", chainId);
+    const [, reclaimAmount, cashOutTaxRate, hookSpecifications] = await client.readContract({
+        address: terminalAddress,
+        abi: jbMultiTerminalAbi,
+        functionName: "previewCashOutFrom",
+        args: [
+            holder,
+            projectId,
+            cashOutCount,
+            tokenToReclaim,
+            beneficiary ?? holder,
+            "0x",
+        ],
+    });
+    // The fee-free surplus counter only matters on zero-tax rulesets.
+    const feeFreeSurplus = cashOutTaxRate === 0n
+        ? await client.readContract({
+            address: terminalAddress,
+            abi: jbMultiTerminalAbi,
+            functionName: "feeFreeSurplusOf",
+            args: [projectId, tokenToReclaim],
+        })
+        : 0n;
+    return resolveCashOutRoute({
+        reclaimAmount,
+        cashOutTaxRate,
+        hookSpecifications,
+        beneficiaryIsFeeless,
+        feeFreeSurplus,
+        slippageBps,
+    });
+}
 //# sourceMappingURL=cashOut.js.map

package/dist/esm/v6/cashOut.js.map

@@ -1 +1 @@
-{"version":3,"file":"cashOut.js","sourceRoot":"","sources":["../../../src/v6/cashOut.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,mBAAmB,EAAE,MAAM,MAAM,CAAC;AACvE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAcvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,cAAc,EACd,kBAAkB,GAAG,EAAE,EACvB,WAAW,EACX,QAAQ,GAAG,IAAI,GAWhB;IACC,OAAO;QACL,OAAO;QACP,OAAO,EAAE,QAAQ;QACjB,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,iBAAiB;QAC/B,IAAI,EAAE;YACJ,MAAM;YACN,SAAS;YACT,YAAY;YACZ,cAAc;YACd,kBAAkB;YAClB,WAAW;YACX,QAAQ;SACT;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACtC,gBAAgB,EAChB,QAAQ,GAIT;IACC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,OAAO,GAAG,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEzE,OAAO,kBAAkB,CACvB,CAAC,cAAc,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,EAC7C,CAAC,OAAO,CAAC,CACH,CAAC;AACX,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAoB,EACpB,EACE,OAAO,EACP,SAAS,EACT,YAAY,EACZ,QAAQ,GAAG,GAAG,EACd,QAAQ,GAAG,MAAM,CAAC,wBAAwB,CAAC,GAO5C;IAED,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;QAC9C,OAAO,EAAE,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC;QAC9C,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,6BAA6B;QAC3C,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC;KAC5D,CAAC,CAAC;IAEH,OAAO;QACL,aAAa;QACb,qBAAqB,EAAE,oBAAoB,CAAC,aAAa,CAAC;KAC3D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cashOut.js","sourceRoot":"","sources":["../../../src/v6/cashOut.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,MAAM,CAAC;AACd,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAcvC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,YAAY,EACZ,cAAc,EACd,kBAAkB,GAAG,EAAE,EACvB,WAAW,EACX,QAAQ,GAAG,IAAI,GAWhB;IACC,OAAO;QACL,OAAO;QACP,OAAO,EAAE,QAAQ;QACjB,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,iBAAiB;QAC/B,IAAI,EAAE;YACJ,MAAM;YACN,SAAS;YACT,YAAY;YACZ,cAAc;YACd,kBAAkB;YAClB,WAAW;YACX,QAAQ;SACT;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACtC,gBAAgB,EAChB,QAAQ,GAIT;IACC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,OAAO,GAAG,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEzE,OAAO,kBAAkB,CACvB,CAAC,cAAc,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC,EAC7C,CAAC,OAAO,CAAC,CACH,CAAC;AACX,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAoB,EACpB,EACE,OAAO,EACP,SAAS,EACT,YAAY,EACZ,QAAQ,GAAG,GAAG,EACd,QAAQ,GAAG,MAAM,CAAC,wBAAwB,CAAC,GAO5C;IAED,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;QAC9C,OAAO,EAAE,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC;QAC9C,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,6BAA6B;QAC3C,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC;KAC5D,CAAC,CAAC;IAEH,OAAO;QACL,aAAa;QACb,qBAAqB,EAAE,oBAAoB,CAAC,aAAa,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAElD,MAAM,OAAO,GAAG,MAAO,CAAC;AAExB,SAAS,UAAU,CAAC,WAAmB;IACrC,IAAI,WAAW,GAAG,EAAE,IAAI,WAAW,IAAI,OAAO,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,cAAsB,6BAA6B;IAEnD,UAAU,CAAC,WAAW,CAAC,CAAC;IACxB,IAAI,MAAM,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,GAAG,WAAW,CAAC,CAAC,GAAG,OAAO,CAAC;IAC3D,OAAO,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,EACjC,aAAa,EACb,cAAc,EACd,oBAAoB,GAAG,KAAK,EAC5B,cAAc,GAAG,EAAE,GAMpB;IACC,IAAI,aAAa,IAAI,EAAE,IAAI,oBAAoB;QAAE,OAAO,EAAE,CAAC;IAC3D,IAAI,cAAc,GAAG,EAAE;QAAE,OAAO,aAAa,GAAG,GAAG,CAAC;IACpD,MAAM,OAAO,GACX,aAAa,GAAG,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,cAAc,CAAC;IAClE,OAAO,OAAO,GAAG,GAAG,CAAC;AACvB,CAAC;AAmBD,MAAM,yBAAyB,GAAG;IAChC,EAAE,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,SAAS,EAAE;IACjD,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,SAAS,EAAE;IAC/C,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,SAAS,EAAE;IACnD,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE;IACnC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE;IAC1C,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;IACnC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE;IACzC,EAAE,IAAI,EAAE,sCAAsC,EAAE,IAAI,EAAE,MAAM,EAAE;CACtD,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAa;IACpD,MAAM,CACJ,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,QAAQ,EACR,aAAa,EACb,MAAM,EACN,YAAY,EACZ,oCAAoC,EACrC,GAAG,mBAAmB,CAAC,yBAAyB,EAAE,QAAQ,CAAC,CAAC;IAC7D,OAAO;QACL,oBAAoB;QACpB,kBAAkB;QAClB,sBAAsB;QACtB,QAAQ;QACR,aAAa;QACb,MAAM;QACN,YAAY;QACZ,oCAAoC;KACrC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAC1C,IAAI,EACJ,oBAAoB,EACpB,IAAI,GAAG,KAAK,GAKb;IACC,IAAI,oBAAoB,GAAG,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,OAAO,GAAG,mBAAmB,CACjC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EACvC,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAC7B,CAAC;IACF,OAAO,kBAAkB,CACvB,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,EACjC,CAAC,OAAO,CAAC,CACH,CAAC;AACX,CAAC;AAwCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GAAG,KAAK,EAC5B,cAAc,GAAG,EAAE,EACnB,WAAW,GAAG,6BAA6B,GAQ5C;IACC,UAAU,CAAC,WAAW,CAAC,CAAC;IACxB,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;QAC7C,aAAa;QACb,cAAc;QACd,oBAAoB;QACpB,cAAc;KACf,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,aAAa,GAAG,mBAAmB,CAAC;IAExD,MAAM,aAAa,GACjB,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC;IACpE,MAAM,OAAO,GAAG,aAAa;QAC3B,CAAC,CAAC;YACE,IAAI,EAAE,aAAa,CAAC,IAAI;YACxB,GAAG,wBAAwB,CAAC,aAAa,CAAC,QAAQ,CAAC;SACpD;QACH,CAAC,CAAC,IAAI,CAAC;IAET,MAAM,aAAa,GAAiB;QAClC,KAAK,EAAE,UAAU;QACjB,cAAc,EAAE,WAAW;QAC3B,aAAa,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC;QACtD,eAAe,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC;QACxD,QAAQ,EAAE,IAAI;QACd,aAAa,EAAE,aAAa;QAC5B,mBAAmB;QACnB,WAAW;QACX,OAAO;KACR,CAAC;IAEF,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,IAAI,IAAI,CAAC,OAAO;QAAE,OAAO,aAAa,CAAC;IAE3E,wEAAwE;IACxE,0EAA0E;IAC1E,2CAA2C;IAC3C,MAAM,KAAK,GACT,OAAO,CAAC,YAAY,GAAG,EAAE;QACvB,CAAC,CAAC,OAAO,CAAC,YAAY;QACtB,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;IACnC,MAAM,aAAa,GACjB,OAAO,CAAC,YAAY,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,oCAAoC;QACxE,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC;QACnC,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;IAEnC,2EAA2E;IAC3E,2EAA2E;IAC3E,IAAI,KAAK,IAAI,EAAE,IAAI,aAAa,IAAI,OAAO,CAAC,sBAAsB,EAAE,CAAC;QACnE,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,cAAc,EAAE,KAAK;QACrB,aAAa;QACb,eAAe,EAAE,EAAE;QACnB,QAAQ,EAAE,2BAA2B,CAAC;YACpC,IAAI,EAAE,aAAa,CAAC,IAAI;YACxB,oBAAoB,EAAE,aAAa;SACpC,CAAC;QACF,aAAa,EAAE,aAAa;QAC5B,mBAAmB;QACnB,WAAW;QACX,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAoB,EACpB,EACE,OAAO,EACP,SAAS,EACT,MAAM,EACN,YAAY,EACZ,cAAc,EACd,WAAW,EACX,QAAQ,EACR,oBAAoB,GAAG,KAAK,EAC5B,WAAW,GAAG,6BAA6B,GAW5C;IAED,MAAM,eAAe,GAAG,QAAQ,IAAI,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;IAC1E,MAAM,CAAC,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,CAAC,GACzD,MAAM,MAAM,CAAC,YAAY,CAAC;QACxB,OAAO,EAAE,eAAe;QACxB,GAAG,EAAE,kBAAkB;QACvB,YAAY,EAAE,oBAAoB;QAClC,IAAI,EAAE;YACJ,MAAM;YACN,SAAS;YACT,YAAY;YACZ,cAAc;YACd,WAAW,IAAI,MAAM;YACrB,IAAI;SACL;KACF,CAAC,CAAC;IAEL,kEAAkE;IAClE,MAAM,cAAc,GAClB,cAAc,KAAK,EAAE;QACnB,CAAC,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC;YACxB,OAAO,EAAE,eAAe;YACxB,GAAG,EAAE,kBAAkB;YACvB,YAAY,EAAE,kBAAkB;YAChC,IAAI,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC;SAClC,CAAC;QACJ,CAAC,CAAC,EAAE,CAAC;IAET,OAAO,mBAAmB,CAAC;QACzB,aAAa;QACb,cAAc;QACd,kBAAkB;QAClB,oBAAoB;QACpB,cAAc;QACd,WAAW;KACZ,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/v6/currency.d.ts

@@ -2,12 +2,10 @@ import { Address } from "viem";
 /**
  * The v6 base currency id for ETH (JBCurrencyIds.ETH).
  *
- * Base currencies are the small standard ids (ETH = 1, USD = 2) used to denominate a
- * ruleset's `baseCurrency` and fund access limits. They are NOT the same as
- * accounting-context currencies, which are derived from a token's address via
- * {@link tokenCurrencyId}. Never use an accounting-context currency (e.g. 61166 for the
- * native token) as a ruleset `baseCurrency` to "skip the price feed" — base currency
- * must be 1 or 2.
+ * ETH = 1 and USD = 2 are well-known shared denominations used by protocol price
+ * feeds. A ruleset's `baseCurrency` may instead be a token-keyed currency from
+ * {@link tokenCurrencyId} when its issuance weight is denominated directly in that
+ * token.
  *
  * @link https://github.com/Bananapus/nana-core-v6/blob/main/src/libraries/JBCurrencyIds.sol
  */
@@ -32,9 +30,11 @@ export declare const NATIVE_TOKEN_CURRENCY_ID = 61166;
  * The v6 accounting-context currency id for a token: `uint32(uint160(tokenAddress))`,
  * i.e. the lowest 4 bytes of the token's address.
  *
- * Use this for terminal accounting contexts (`{ token, decimals, currency }`) — NOT for
- * a ruleset's `baseCurrency`, which must be a base currency id
- * ({@link BASE_CURRENCY_ETH} or {@link BASE_CURRENCY_USD}).
+ * Use this for terminal accounting contexts (`{ token, decimals, currency }`). It may
+ * also be used as a ruleset's `baseCurrency` when issuance is denominated directly in
+ * that token. Use a shared denomination such as {@link BASE_CURRENCY_ETH} or
+ * {@link BASE_CURRENCY_USD} when multiple accepted tokens must be converted through
+ * price feeds.
  *
  * @param token The token address to derive a currency id from.
  * @returns The token's accounting-context currency id (fits in a uint32).

package/dist/esm/v6/currency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../../src/v6/currency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../../src/v6/currency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/dist/esm/v6/currency.js

@@ -1,12 +1,10 @@
 /**
  * The v6 base currency id for ETH (JBCurrencyIds.ETH).
  *
- * Base currencies are the small standard ids (ETH = 1, USD = 2) used to denominate a
- * ruleset's `baseCurrency` and fund access limits. They are NOT the same as
- * accounting-context currencies, which are derived from a token's address via
- * {@link tokenCurrencyId}. Never use an accounting-context currency (e.g. 61166 for the
- * native token) as a ruleset `baseCurrency` to "skip the price feed" — base currency
- * must be 1 or 2.
+ * ETH = 1 and USD = 2 are well-known shared denominations used by protocol price
+ * feeds. A ruleset's `baseCurrency` may instead be a token-keyed currency from
+ * {@link tokenCurrencyId} when its issuance weight is denominated directly in that
+ * token.
  *
  * @link https://github.com/Bananapus/nana-core-v6/blob/main/src/libraries/JBCurrencyIds.sol
  */
@@ -31,9 +29,11 @@ export const NATIVE_TOKEN_CURRENCY_ID = 61166;
  * The v6 accounting-context currency id for a token: `uint32(uint160(tokenAddress))`,
  * i.e. the lowest 4 bytes of the token's address.
  *
- * Use this for terminal accounting contexts (`{ token, decimals, currency }`) — NOT for
- * a ruleset's `baseCurrency`, which must be a base currency id
- * ({@link BASE_CURRENCY_ETH} or {@link BASE_CURRENCY_USD}).
+ * Use this for terminal accounting contexts (`{ token, decimals, currency }`). It may
+ * also be used as a ruleset's `baseCurrency` when issuance is denominated directly in
+ * that token. Use a shared denomination such as {@link BASE_CURRENCY_ETH} or
+ * {@link BASE_CURRENCY_USD} when multiple accepted tokens must be converted through
+ * price feeds.
  *
  * @param token The token address to derive a currency id from.
  * @returns The token's accounting-context currency id (fits in a uint32).

package/dist/esm/v6/currency.js.map

@@ -1 +1 @@
-{"version":3,"file":"currency.js","sourceRoot":"","sources":["../../../src/v6/currency.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"currency.js","sourceRoot":"","sources":["../../../src/v6/currency.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC;AAC7C,CAAC"}

package/dist/esm/v6/launch.d.ts

@@ -25,17 +25,19 @@ export declare function getProjectCreationFee(client: PublicClient, chainId: JBC
 /**
  * Build a `JBAccountingContext` for a token.
  *
- * The context currency is ALWAYS token-keyed: `uint32(uint160(token))`
- * (native token → 61166). This is distinct from a ruleset's `baseCurrency`,
- * which must be a standard currency id (ETH=1, USD=2) — never use a
- * token-keyed currency as a base currency to "skip the price feed".
+ * By default the context currency is token-keyed: `uint32(uint160(token))`
+ * (native token → 61166). Pass an explicit shared currency such as ETH=1 or
+ * USD=2 when the terminal should convert this token through a protocol price
+ * feed. A ruleset's `baseCurrency` is the denomination used to interpret its
+ * issuance weight.
  *
  * @param token The token address. Defaults to the native token sentinel
  * (`0x…EEEe`).
  * @param decimals The token's decimals. Defaults to 18 for the native token;
  * REQUIRED for any other token (there is no safe default).
+ * @param currency The context's currency id. Defaults to the token-keyed id.
  */
-export declare function buildAccountingContext(token?: Address, decimals?: number): JBAccountingContext;
+export declare function buildAccountingContext(token?: Address, decimals?: number, currency?: number): JBAccountingContext;
 /**
  * Build the standard terminal configurations for a launch:
  *