@black-market/sdk 0.10.0 → 0.12.0

package/dist/lifecycle/ufg.js

@@ -0,0 +1,98 @@
+import { decodeFunctionResult, encodeFunctionData, keccak256, stringToHex, zeroAddress } from "viem";
+import { lifecycleErc20Abi } from "./abi.js";
+import { ufgLaunchProxyV1Abi, ufgTreasuryFactoryV1Abi } from "./ufg-abi.js";
+import { buildLaunchTransactions } from "./transactions.js";
+import { decodeAbyssLifecycleMarketConfig, encodeAbyssLifecycleMarketConfig, decodePoolBoundV4LifecycleMarketConfig } from "./markets.js";
+import { getKnownLifecycleProfile, KnownLifecycleProfile } from "./presets.js";
+import { LifecycleFundingKind, LifecycleTokenKind, LifecycleRewardMode, LifecycleMode } from "./schema.js";
+import { LifecyclePlanningError } from "./types.js";
+import { buildUfgFeeAssetPolicies, encodeUfgLaunchConfig, hashUfgLaunchConfig, isUfgProfile, UFG_DYNAMIC_ADAPTER_ID, UFG_FIXED_ADAPTER_ID, UFG_FIXED_PROFILE_ID, UFG_LAUNCH_PROXY_ADDRESS, UFG_TREASURY_FACTORY_ADDRESS, ufgPlanPrincipal } from "./ufg-config.js";
+export { UFG_LAUNCH_PROXY_ADDRESS, UFG_TREASURY_FACTORY_ADDRESS, UFG_UPSTREAM_FACTORY_ADDRESS, UFG_ORCHESTRATOR_ADDRESS, UFG_FIXED_PROFILE_ID, UFG_DYNAMIC_PROFILE_ID, UFG_FIXED_ADAPTER_ID, UFG_DYNAMIC_ADAPTER_ID, isUfgProfile, ufgLaunchConfigComponents, encodeUfgLaunchConfig, decodeUfgLaunchConfig, hashUfgLaunchConfig, validateUfgLaunchConfig, ufgLaunchNonce, buildUfgFeeAssetPolicies } from "./ufg-config.js";
+/** Offline proxy-specific admission. Live token/reserve code, registry and transfer checks still require simulation. */
+export function validateUfgLaunchPlan(plan, config, predictedToken) {
+    try {
+        ufgPlanPrincipal(plan);
+        encodeUfgLaunchConfig(config);
+        if (plan.token.kind !== LifecycleTokenKind.ERC20 || plan.token.rewardMode !== LifecycleRewardMode.None || plan.executorFeeBps !== 0 || plan.markets.length === 0 || plan.token.inventoryRecipient.toLowerCase() === UFG_LAUNCH_PROXY_ADDRESS.toLowerCase() || plan.buys.some((buy) => buy.recipient.toLowerCase() === UFG_LAUNCH_PROXY_ADDRESS.toLowerCase()))
+            throw new Error("UFG requires ERC20/no rewards, zero executor fee, markets and external inventory/buy recipients");
+        const expected = buildUfgFeeAssetPolicies(predictedToken, config.reserveAssets);
+        if (plan.feeAssets.length !== expected.length || plan.feeAssets.some((policy, index) => {
+            const required = expected[index];
+            return policy.asset.toLowerCase() !== required.asset.toLowerCase() || policy.ownerBps !== required.ownerBps || policy.rewardsBps !== 0 || policy.burnBps !== required.burnBps;
+        }))
+            throw new Error("UFG fee policies must burn all token fees and send all reserve fees to the owner, in ascending asset order");
+        const reserves = new Set(config.reserveAssets.map((asset) => asset.toLowerCase()));
+        const quotes = new Set(plan.markets.map((market) => market.quoteAsset.toLowerCase()));
+        if (reserves.size !== quotes.size || [...quotes].some((quote) => !reserves.has(quote)))
+            throw new Error("Every reserve must be a market quote and every market quote a reserve");
+        const configHash = hashUfgLaunchConfig(config);
+        for (const market of plan.markets) {
+            if (market.configVersion === 1) {
+                const inner = decodeAbyssLifecycleMarketConfig(market.config);
+                const profile = getKnownLifecycleProfile({ chainId: plan.chainId, orchestrator: plan.orchestrator, key: inner.profile === 2 ? KnownLifecycleProfile.Abyss2 : KnownLifecycleProfile.Abyss3 });
+                if (market.adapterId.toLowerCase() !== keccak256(stringToHex("black-market.adapter.abyss-lifecycle.v1")) || (inner.profile !== 2 && inner.profile !== 3) || market.profileId.toLowerCase() !== profile?.profile.id || encodeAbyssLifecycleMarketConfig(inner).toLowerCase() !== market.config.toLowerCase())
+                    throw new Error("UFG Abyss markets require canonical QUOTE or QUOTE_ORACLE config1 without a tail");
+            }
+            else if (market.configVersion === 6) {
+                if (!isUfgProfile(market.profileId))
+                    throw new Error("UFG config6 markets require an admitted UFG fixed or dynamic profile");
+                const inner = decodePoolBoundV4LifecycleMarketConfig(market.config, 6);
+                const adapterId = market.profileId.toLowerCase() === UFG_FIXED_PROFILE_ID ? UFG_FIXED_ADAPTER_ID : UFG_DYNAMIC_ADAPTER_ID;
+                if (market.adapterId.toLowerCase() !== adapterId || inner.profileId.toLowerCase() !== market.profileId.toLowerCase() || inner.version !== 6 || inner.feeMode !== 1 || inner.lpFeePips !== 0 || inner.ufgLaunchConfig === undefined || hashUfgLaunchConfig(inner.ufgLaunchConfig) !== configHash)
+                    throw new Error("Every UFG config6 market requires QuoteOnly, zero LP fee and the identical canonical proxy config tail");
+            }
+            else
+                throw new Error("UFG supports only canonical Abyss config1 and UFG pool-bound config6");
+        }
+    }
+    catch (error) {
+        if (error instanceof LifecyclePlanningError && error.code === "INVALID_UFG_PLAN")
+            throw error;
+        throw new LifecyclePlanningError("INVALID_UFG_PLAN", error instanceof Error ? error.message : "Invalid UFG launch plan");
+    }
+}
+/** Pure unsigned proxy commands; account is the principal encoded in plan.nonce. */
+export function buildUfgLaunchTransactions(options) {
+    const { plan, config } = options;
+    const principal = ufgPlanPrincipal(plan);
+    encodeUfgLaunchConfig(config);
+    return buildLaunchTransactions(options).map((transaction) => {
+        const data = transaction.kind === "atomic" ? encodeFunctionData({ abi: ufgLaunchProxyV1Abi, functionName: "launchAtomic", args: [plan, config] })
+            : transaction.kind === "begin" ? encodeFunctionData({ abi: ufgLaunchProxyV1Abi, functionName: "beginLaunch", args: [plan, LifecycleMode.Staged, config] }) : transaction.data;
+        return { ...transaction, from: principal, to: UFG_LAUNCH_PROXY_ADDRESS, data, calldataBytes: (data.length - 2) / 2 };
+    });
+}
+export function buildUfgCancelTransaction({ plan, preparedMarkets = 0 }) {
+    const data = encodeFunctionData({ abi: ufgLaunchProxyV1Abi, functionName: "cancelLaunch", args: [plan] });
+    return { id: "cancel", kind: "cancel", chainId: Number(plan.chainId), from: ufgPlanPrincipal(plan), to: UFG_LAUNCH_PROXY_ADDRESS, data, calldataBytes: (data.length - 2) / 2, value: 0n, dependencies: [], postconditions: [{ kind: "launch", phase: "Cancelled", preparedMarkets }] };
+}
+/** Exact summed proxy pulls, not escrow allowances. Current allowance/reset discovery belongs to planning. */
+export function buildUfgApprovals(plan) {
+    const principal = ufgPlanPrincipal(plan);
+    const totals = new Map();
+    for (const funding of plan.funding) {
+        if (funding.kind === LifecycleFundingKind.NativeWrap || BigInt(funding.inputAsset) === 0n)
+            continue;
+        const asset = funding.kind === LifecycleFundingKind.ERC20 ? funding.asset : funding.inputAsset;
+        const amount = funding.kind === LifecycleFundingKind.ERC20 ? funding.amount : funding.inputAmount;
+        const key = asset.toLowerCase();
+        const entry = totals.get(key);
+        if (entry === undefined)
+            totals.set(key, { asset, amount });
+        else
+            entry.amount += amount;
+    }
+    const transactions = [...totals.values()].map(({ asset, amount }) => {
+        const data = encodeFunctionData({ abi: lifecycleErc20Abi, functionName: "approve", args: [UFG_LAUNCH_PROXY_ADDRESS, amount] });
+        return { id: `approve:${asset}`, kind: "approve", chainId: Number(plan.chainId), from: principal, to: asset, data, calldataBytes: (data.length - 2) / 2, value: 0n, dependencies: [], postconditions: [{ kind: "allowance", asset, spender: UFG_LAUNCH_PROXY_ADDRESS, minimum: amount }] };
+    });
+    return transactions.map((transaction, index) => ({ ...transaction, dependencies: index === 0 ? [] : [transactions[index - 1].id] }));
+}
+/** Read-only upstream treasury lookup. No treasury is represented by undefined, not the zero address. */
+export async function readUfgTreasury(client, token) {
+    const data = encodeFunctionData({ abi: ufgTreasuryFactoryV1Abi, functionName: "treasuryOf", args: [token] });
+    const result = await client.request({ method: "eth_call", params: [{ to: UFG_TREASURY_FACTORY_ADDRESS, data }, "latest"] });
+    const treasury = decodeFunctionResult({ abi: ufgTreasuryFactoryV1Abi, functionName: "treasuryOf", data: result });
+    return treasury === zeroAddress ? undefined : treasury;
+}
+//# sourceMappingURL=ufg.js.map

package/dist/lifecycle/ufg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ufg.js","sourceRoot":"","sources":["../../src/lifecycle/ufg.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAgB,MAAM,MAAM,CAAC;AACnH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,gCAAgC,EAAE,sCAAsC,EAAE,MAAM,cAAc,CAAC;AAC1I,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,aAAa,EAAqB,MAAM,aAAa,CAAC;AAC9H,OAAO,EAAE,sBAAsB,EAA2F,MAAM,YAAY,CAAC;AAC7I,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,gBAAgB,EAAwB,MAAM,iBAAiB,CAAC;AAEzR,OAAO,EAAE,wBAAwB,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,YAAY,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,cAAc,EAAE,wBAAwB,EAAwB,MAAM,iBAAiB,CAAC;AAElb,wHAAwH;AACxH,MAAM,UAAU,qBAAqB,CAAC,IAAkB,EAAE,MAAuB,EAAE,cAAuB;IACxG,IAAI,CAAC;QACH,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACvB,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,kBAAkB,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,KAAK,mBAAmB,CAAC,IAAI,IAAI,IAAI,CAAC,cAAc,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,WAAW,EAAE,KAAK,wBAAwB,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,wBAAwB,CAAC,WAAW,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iGAAiG,CAAC,CAAC;QACld,MAAM,QAAQ,GAAG,wBAAwB,CAAC,cAAc,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;QAChF,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YACrF,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAE,CAAC;YAClC,OAAO,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,IAAI,MAAM,CAAC,UAAU,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,CAAC;QAChL,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4GAA4G,CAAC,CAAC;QAClI,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QACnF,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QACtF,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QACjL,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC/C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,KAAK,GAAG,gCAAgC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC9D,MAAM,OAAO,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC7L,IAAI,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,CAAC,yCAAyC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,gCAAgC,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;YACnZ,CAAC;iBAAM,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;gBAC7H,MAAM,KAAK,GAAG,sCAAsC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;gBACvE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,oBAAoB,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,sBAAsB,CAAC;gBAC1H,IAAI,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,KAAK,CAAC,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,IAAI,mBAAmB,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,UAAU;oBAAE,MAAM,IAAI,KAAK,CAAC,wGAAwG,CAAC,CAAC;YAC7Z,CAAC;;gBAAM,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,sBAAsB,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB;YAAE,MAAM,KAAK,CAAC;QAC9F,MAAM,IAAI,sBAAsB,CAAC,kBAAkB,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC;IAC3H,CAAC;AACH,CAAC;AAGD,oFAAoF;AACpF,MAAM,UAAU,0BAA0B,CAAC,OAA0C;IACnF,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACjC,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE;QAC1D,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,EAAE,GAAG,EAAE,mBAAmB,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;YAC/I,CAAC,CAAC,WAAW,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,EAAE,GAAG,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC;QAChL,OAAO,EAAE,GAAG,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,wBAAwB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACvH,CAAC,CAAC,CAAC;AACL,CAAC;AACD,MAAM,UAAU,yBAAyB,CAAC,EAAE,IAAI,EAAE,eAAe,GAAG,CAAC,EAAoD;IACvH,MAAM,IAAI,GAAG,kBAAkB,CAAC,EAAE,GAAG,EAAE,mBAAmB,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1G,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,wBAAwB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;AACzR,CAAC;AACD,8GAA8G;AAC9G,MAAM,UAAU,iBAAiB,CAAC,IAAkB;IAClD,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8C,CAAC;IACrE,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,IAAI,KAAK,oBAAoB,CAAC,UAAU,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE;YAAE,SAAS;QACpG,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,KAAK,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;QAC/F,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,KAAK,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;QAClG,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;;YAAM,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC;IAC3F,CAAC;IACD,MAAM,YAAY,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAwB,EAAE;QACxF,MAAM,IAAI,GAAG,kBAAkB,CAAC,EAAE,GAAG,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,wBAAwB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC/H,OAAO,EAAE,EAAE,EAAE,WAAW,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC7R,CAAC,CAAC,CAAC;IACH,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,WAAW,EAAE,YAAY,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,GAAG,CAAC,CAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACxI,CAAC;AACD,yGAAyG;AACzG,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAA0B,EAAE,KAAc;IAC9E,MAAM,IAAI,GAAG,kBAAkB,CAAC,EAAE,GAAG,EAAE,uBAAuB,EAAE,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC7G,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,4BAA4B,EAAE,IAAI,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC5H,MAAM,QAAQ,GAAG,oBAAoB,CAAC,EAAE,GAAG,EAAE,uBAAuB,EAAE,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAuB,EAAE,CAAC,CAAC;IACnI,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;AACzD,CAAC"}

package/docs/launch-lifecycle.md

@@ -7,6 +7,188 @@ The canonical authorities are the registry/certification/adapter/config contract
 in the protocol repository. Plan identity is `LaunchPlanV1`. Pool-bound V4 uses **config 6**,
 canonical Abyss uses **config 1**, and generic current shared-V4 support uses **config 4**.
 
+## 0.12.0 release: opt-in UFG treasuries
+
+UFG is an additive **proxy launch route**, not a new token kind or a replacement
+for the core path. Existing launch defaults, calldata, salts and HMM behavior are
+unchanged when `ufg` is omitted. The pinned Robinhood deployment (chain **4663**) is:
+
+| Export | Address |
+| --- | --- |
+| `UFG_LAUNCH_PROXY_ADDRESS` | `0xf6673d859DE03eB74A0b01696Edb97f941dFD0CA` |
+| `UFG_TREASURY_FACTORY_ADDRESS` | `0x26Aa5D52134c8E6c4C01E9fb53A7568c0C64901F` |
+| `UFG_UPSTREAM_FACTORY_ADDRESS` | `0xA170b5A58C111334A7237F2Ea2c428ec5022f68E` |
+| `UFG_ORCHESTRATOR_ADDRESS` | `0x91560876033d568d25CDe98C78c33ff8FC43962c` |
+
+`KnownLifecycleProfile.V4UfgFixedPool` (`v4-ufg-fixed-pool`) selects profile
+`0x5c6045af480814e469f3dba7c120d264047c9320b869c63a064536041a2dbae6`;
+`V4UfgDynamicPool` (`v4-ufg-dynamic-pool`) selects
+`0x03de8d5e38f2957d80ecb9f2e59d555601ff091dfb17bce84178956a2e8d9b41`.
+`isUfgProfile` recognizes only these IDs. Frozen envelopes, adapter/registration/
+topology and bound-hook metadata come from committed registry readback at block
+**94,551,140** (`test/fixtures/ufg-registry-readback.json`). Regenerate with
+`node --experimental-transform-types scripts/generate-ufg-presets.mjs /path/to/black-market`;
+add `--readback` only to recapture that exact block with read-only RPC.
+The fixed and zero-royalty dynamic creation bytes exactly match the existing
+`FixedFeePoolV1` / `DynamicFeePoolV1` artifacts, so no duplicate hook enum is needed.
+UFG deployers, lockers, collectors and adapters are nevertheless different graphs.
+Frozen presets are construction evidence, not live admission.
+
+### Configuration and supported markets
+
+`UfgLaunchConfig` is `{ treasuryShareBps, exitFeeBps, reserveAssets }`. The proxy
+requires treasury share **10000**, integer exit fee **0..2000 bps**, and **1..7**
+nonzero, unique, strictly ascending reserve addresses, excluding the predicted
+launch token. Reserves and market quotes must form exactly the same set.
+
+- ERC20 only, no staking/dividends, zero executor fee and at least one market.
+  Neither inventory nor initial-buy recipients may be the proxy.
+- Native Abyss uses the canonical adapter with config1 profile **2 (QUOTE)** or
+  **3 (QUOTE_ORACLE)** and the matching canonical profile ID. Its canonical
+  config has **no tail**.
+- V4 uses config6 and one of the two UFG profiles, `feeMode: 1` (QuoteOnly) and
+  `lpFeePips: 0`. Preset zero-royalty terms still apply. Supply/position budgets,
+  price/ranges, oracle registration and ordinary lifecycle bounds are unchanged.
+- Fee policies contain exactly the token plus reserves in ascending order:
+  token `{ ownerBps: 0, rewardsBps: 0, burnBps: 10000 }`, reserves
+  `{ ownerBps: 10000, rewardsBps: 0, burnBps: 0 }`.
+  `buildUfgFeeAssetPolicies(predictedToken, reserveAssets)` builds that exact set;
+  reserve ordering is validated, never silently repaired.
+
+`encodeUfgLaunchConfig` encodes **one dynamic tuple**:
+`abi.encode((uint16,uint16,address[]))`, including the leading `0x20` offset.
+`decodeUfgLaunchConfig` checks canonical re-encoding; trailing bytes, alternate
+offsets and dirty padding are rejected. `hashUfgLaunchConfig` is its keccak256.
+Config6's typed `ufgLaunchConfig` automatically appends that encoding after the
+canonical V6 prefix and decodes/splits it on read. Every UFG V4 tail must equal
+the proxy config. The constructor economics hash remains **prefix-only with zero
+hook salt**; the full plan hash binds the tail. No UFG tail is added to ordinary
+V4, HMM or Abyss configs. Independent `cast abi-encode` fixtures are regenerated
+with `node scripts/generate-ufg-fixtures.mjs`.
+
+### Principal funding, planning and recovery
+
+The economic plan's **creator is the proxy**. Its nonce is
+`ufgLaunchNonce(principal, nonce96) = (uint160(principal) << 96) | nonce96`.
+The `account` and every sender are the **same principal**, never the proxy.
+The core still derives launch ID/token from the committed core/proxy/nonce.
+
+```ts
+const config = {
+  treasuryShareBps: 10000, exitFeeBps: 100,
+  reserveAssets: [getAddresses(4663).weth],
+};
+// economicPlan already contains your full token/funding/market/buy economics;
+// every UFG V4 market was encoded with this same ufgLaunchConfig.
+const plan = { ...economicPlan, creator: UFG_LAUNCH_PROXY_ADDRESS,
+  nonce: ufgLaunchNonce(principal, 1n) };
+const token = await client.readContract({ address: plan.orchestrator,
+  abi: launchLifecycleAbi, functionName: "predictToken", args: [plan] });
+plan.feeAssets = buildUfgFeeAssetPolicies(token, config.reserveAssets);
+validateUfgLaunchPlan(plan, config, token); // pure/offline proxy rules
+const planned = await prepareAndPlanLifecycleLaunch({
+  client, account: principal, plan, mode: "staged", ufg: { config },
+});
+// No signing here. Obtain fresh admitted proxy envelopes before wallet execution:
+const next = await buildNextTransaction({ client, planned });
+```
+
+The opt-in works on `planLaunch` too. `PlannedLaunch.ufg` retains config and its
+hash; `simulateLaunchPlan`, `readLaunchProgress`, and `buildNextTransaction`
+(including `action: "cancel"`) retain the route and reject config mutation,
+wrong principal/nonce, wrong receipt target/config, or proxy binding mismatch.
+Salt mining and optional buy-minimum calibration use the existing machinery.
+Native Nitro metering/execution proofs remain mandatory on production chain4663.
+
+The proxy pulls summed non-native inputs from the principal: ERC20 asset/amount
+or swap inputAsset/inputAmount. **Approve the proxy, not the funding escrow**.
+`buildUfgApprovals(plan)` builds exact summed approvals; planning observes current
+allowances and includes zero-reset commands when needed. Native-wrap and native
+swap inputs are `msg.value` on atomic/begin only. Refunds return to the principal.
+
+Pure `buildUfgLaunchTransactions({ plan, config, mode, preparationBatches })`
+produces proxy `launchAtomic(plan, config)`, or `beginLaunch(plan, Staged, config)`,
+ordered `prepareMarkets` batches, then `activateLaunch`. The explicit batches
+must cover all markets. `buildUfgCancelTransaction({ plan, preparedMarkets })`
+targets the same proxy. These builders alone do not establish execution admission.
+`validateUfgLaunchPlan` checks offline proxy rules; live registry continuity,
+reserve/token code and supply bounds, transfers and treasury creation require RPC
+simulation. The existing non-UFG core transaction builder is intentionally unchanged.
+
+`readUfgTreasury(client, token)` reads the treasury factory's `treasuryOf(token)`
+and returns the upstream address, or `undefined` for zero. Complete
+`ufgLaunchProxyV1Abi`, `ufgTreasuryFactoryV1Abi`, `ufgBlackMarketFactoryAbi` and
+`ufgBlackMarketTreasuryAbi` expose proxy config hashes and upstream treasury
+collect/redeem/assets/backing/position/debt operations without inventing wrappers.
+The pure example is `node examples/ufg-launch-config.ts` after building.
+
+### UFG owned-fork check
+
+This explicitly authorized local-only integration uses the unlocked Anvil default
+account, no keys, and only public SDK launch APIs. In separate terminals:
+
+```sh
+anvil --fork-url https://rpc.mainnet.chain.robinhood.com/ \
+  --chain-id 4663 --port 8561 \
+  --gas-limit 100000000 --silent
+pnpm build
+UFG_FORK_RPC_URL=http://127.0.0.1:8561 node test/integration/ufg-launch.fork.mjs
+```
+
+It validates the tuple against the deployed factory, mines bound-hook salts,
+executes Abyss QUOTE atomic, mixed Abyss QUOTE + UFG fixed staged (ERC20 funding/
+proxy approval), and UFG dynamic atomic launches. It calls each exact proxy
+command from the principal first, then checks Active, a nonzero `readUfgTreasury`
+and `proxy.launchConfigHash == hashUfgLaunchConfig`. Snapshot restoration makes
+the check repeatable. Stop Anvil afterward. Generic Anvil proves EVM contract
+behavior here, **not ArbOS compute/poster admission**: construction/read/mining/
+unsigned APIs plus actual fork `eth_call`/receipts are used, not a fake native
+Nitro planner certificate. Ordinary `pnpm test` never runs this funded check.
+
+## 0.11.0 release: gas sizing, packing and prefix proof
+
+New atomic/activation envelopes containing HMM V2 markets add one forwarding target:
+`R = 4_250_000 + 500_000 * (hmmMarkets - 1)` gas (zero for non-HMM plans).
+For measured gross gas `G` (`maxUsedGas`, falling back to `gasUsed`), compute is
+`min(max(G + R, ceil(G * (10000 + headroomBps) / 10000)), computeCap)`.
+Begin/preparation/approval/cancel commands do not receive this reserve. Nitro poster
+gas is budgeted separately inside the same complete gas envelope. Optional padding
+and the reserve are targets, not refusal thresholds; exact validated replay proves
+the clamped envelope. There is no bisection or extra ordinary-path request.
+
+Staged planning greedily packs contiguous markets against the unpadded compute cap:
+HMM V2 costs 14.5M per market; other profiles cost a conservative 16M. At 32M,
+1/2/3/5 HMM markets produce `[1]`/`[2]`/`[2,1]`/`[2,2,1]`.
+Only a packed measurement failure consuming at least 95% of its given gas splits
+that batch in half, regardless of its error selector. Low-gas semantic failures
+remain failures. `preparationBatchSize` is removed; inspect each preparation's
+`marketStart`/`marketCount`. The pure unsigned compiler still accepts explicit
+`preparationBatches`.
+
+Robinhood chain 4663 defaults `limits.maxSimulationGas` to **50_000_000n** aggregate
+gas **used**, not the sum of individual legal transaction envelopes. Override it
+for a provider with a different budget. The SDK measures and validates the longest
+estimated prefix that fits: begin 9.5M, preparations as above, activation 6M per
+market plus `R`, and small approvals/cancellation. A measurement failure after
+cumulative use reaches 95% of that cap defers the failed call and suffix.
+If even the immediate estimate cannot fit that budget, refusal first identifies
+any estimated per-transaction compute overflow (gas displayed in millions to one
+decimal), rather than suggesting that a larger RPC budget solves it. Estimates
+alone do not reject an envelope that can still be measured and exactly proved.
+
+`simulation.admitted`, `executionProof: "proved"` and `protocolFit: "proved"` cover
+only the successful proven prefix. **They do not promise eventual activation.**
+`simulation.deferredTransactionIds` explicitly lists unproved remaining steps
+(empty for full coverage); these commands carry no `gas`, `gasPrice`, `estimate`
+or `admission`. Call `buildNextTransaction` before each signature: canonical
+progress advances the proof window and gives the immediate next transaction exact
+gas. Reviewed envelopes receive only a direct exact replay of that immediate step,
+without new measurement, poster/price recommendations or suffix proof.
+
+`buySlippageBps` requires actual activation outputs. If activation is deferred,
+calibration refuses clearly; use a higher-budget native provider or preserve
+already committed minima by omitting recalibration. Outputs are never fabricated.
+
 ## 0.9.1 release: Abyss 0.01% fee tier
 
 `ABYSS_FEE_TIERS` now includes `{ feePips: 100, tickSpacing: 1, label: "0.01%" }`.
@@ -342,15 +524,13 @@ progress, funding/allowances and deployment/profile authority. It matches
 Preparation batching remains SDK-derived, not caller-selected. Malformed,
 wrong-step or changed envelopes refuse without returning executable calldata.
 
-Fresh measurement and complete native validated replay use the held price.
-The immediate replay uses the exact held gas; later unfinished steps receive
-fresh gas bounds and remain in the same stateful sequence. Current compute,
-poster, minimum headroom, tightening ceilings and full-sequence actual-balance
-affordability still apply. Exact replay also checks gross-gas headroom without
-counting Nitro's temporary compute hold. Neither natural child base fees nor
-payer balances are overridden. A higher advisory quote alone is not a refusal;
-an invalid current fee, insufficient gas or failed proof never silently raises
-the held envelope.
+The SDK directly validates only the immediate transaction at its exact held
+gas/price. It does not repeat measurement, quote a new gas price/poster budget or
+simulate future steps. Current protocol/transaction limits, native metering,
+postconditions and immediate actual-balance affordability still apply. Existing
+padding may be consumed; neither a new padding target nor a higher advisory quote
+alone invalidates a held envelope. Natural child base fees and payer balances are
+never overridden, and failed replay never raises held gas or switches backend.
 
 Approvals/resets, atomic launches, every staged next step and cancellation use
 this same contract. Cancellation retains its adapter-independent recovery policy.
@@ -742,13 +922,13 @@ Validation uses `validateV4LifecycleMarket`; the collector factory getter is
 | --- | --- |
 | `readLifecycleProfiles({client, orchestrator, profileIds?, offset?, limit?})` | Bounded registry discovery, schema/topology dispatch, reviewed graph/terms certification and current registry admission. Default offset/limit is 0/100; explicit IDs can select a reviewed deployment's identities. |
 | `predictLifecycleToken({client, plan})` | Exact prediction from the explicit core. |
-| `prepareAndPlanLifecycleLaunch({client, account, plan, mode, allowTopologyGaps?, allowMissingPermanentTail?, limits?, fork?, receipts?, confirmations?, signal?, onProgress?})` | Mines config6/V2 salts offchain, verifies per-market launch topology and exact final deployment bindings, and returns complete selected-mode admission under one SDK-owned fresh post-mining snapshot. No source-chain deployment or broadcast. |
+| `prepareAndPlanLifecycleLaunch({client, account, plan, mode, buySlippageBps?, allowTopologyGaps?, allowMissingPermanentTail?, limits?, fork?, receipts?, confirmations?, signal?, onProgress?})` | Mines config6/V2 salts offchain, verifies per-market topology and exact final deployment bindings, and proves the selected-mode prefix under one fresh post-mining snapshot. Reports deferred steps; buy calibration requires activation coverage. No source-chain deployment or broadcast. |
 | `readPoolBoundHookDeployment({client, plan, marketIndex})` | Verifies typed factory, code chunks, constructor, normalized economics, initcode, salt, CREATE2 prediction and recorded provenance of existing code. Works with draft salts; permission bits are additionally required for executable predeployment. |
 | `buildPoolBoundHookDeploymentTransaction({client, plan, marketIndex})` | Optional permissionless typed `deploy(parameters,salt)` calldata. Does not create a token, register/initialize a pool, bind a collector or activate a launch. |
 | `planLaunch({client, account, plan, mode, allowTopologyGaps?, allowMissingPermanentTail?, limits?, fork?, receipts?, confirmations?, signal?})` | Independently fresh per-market topology/domain/funding/profile/progress/execution admission of the already-finalized commitment, simulating only the explicitly selected mode. |
 | `simulateLaunchPlan({client, planned, limits?, fork?, receipts?, confirmations?})` | Rereads canonical state and proves remaining work. Preserves receipt evidence, economics and selected mode. |
 | `readLaunchProgress({client, planned, receipts?, confirmations?})` | Confirmation-bound canonical state, latest head, receipt/replacement/reorg status, account-nonce safety and actual prepared market/live state. |
-| `buildNextTransaction({client, planned, reviewedTransaction?, submissionClient?, limits?, fork?, receipts?, confirmations?, action?})` | Rereads progress, constraints and complete stateful proof before returning one admitted transaction. Optional untrusted `reviewedTransaction` must match the current canonical next step and freshly prove its exact gas/price. Optional `submissionClient` adds read-only immediate exact-envelope preflight. `action: "cancel"` uses the stored commitment without requiring fresh adapter/profile admission. Terminal launches return `undefined`. |
+| `buildNextTransaction({client, planned, reviewedTransaction?, submissionClient?, limits?, fork?, receipts?, confirmations?, action?})` | Rereads canonical progress and constraints, proves the immediate next transaction plus the fitting prefix, and returns one admitted envelope. With `reviewedTransaction`, directly replays only that matching immediate step at its exact held gas/price. Optional `submissionClient` adds read-only exact-envelope preflight. `action: "cancel"` retains adapter-independent recovery. Terminal launches return `undefined`. |
 
 Clients may be viem public clients or raw `request({method,params})` RPC clients. Transport, wallet, signing and durable storage are application-owned. `PlannedLaunch` contains bigint values and live limit callbacks: persist `serializeLaunchPlan(plan)`, explicit execution mode, confirmation policy and receipt references, not the entire object.
 
@@ -879,17 +1059,17 @@ Mining is cancellable/nonblocking; `abort()` raises `AbortError` and does not ca
 Every planning call requires `mode: "atomic" | "staged"`. Only that requested mode receives economic simulation; staged does not compute or expose an unused atomic attempt.
 
 - Atomic: after funding prerequisites, token creation, empty infrastructure, all mint/lock/buys/public activation are one transaction.
-- Staged: prerequisites, `beginLaunch(Staged)`, contiguous empty `prepareMarkets` batches, then one `activateLaunch`. Only a stateful preparation refusal classified as capacity with a compute or gas-envelope constraint can partition into smaller empty batches. Opaque `DeploymentFailed`, unclassified/source/provider-clamp errors, byte-cap refusals and near-cap consumption do not authorize that search. Core/validator/registry/hook invariant errors stop planning.
+- Staged: prerequisites, `beginLaunch(Staged)`, greedily packed contiguous empty `prepareMarkets` batches, then one `activateLaunch`. A packed measurement failure using at least 95% of its given gas splits only that batch; low-gas semantic errors, byte caps and unlocated provider failures do not justify a split. Proof may cover only a prefix, with the unproved suffix explicitly deferred.
 - Activation cannot split. If mint/lock/all buys/opening cannot fit, staged is also refused. No position/buy/minimum is omitted to manufacture success.
 
 No automatic atomic-to-staged fallback exists. Obtain separate consent to review the same commitment as staged. Both venues use token transfer restrictions plus activation-time canonical opening-state checks, not a pool gate. Manipulated opening price or preactivation liquidity fails verification; the token stays inactive and the launch remains Ready/cancellable. Failed activation rolls back every mint, seal, buy and opening together.
 
 ## Execution constraints and stateful simulation
 
-Optional `chainGasLimit`, `rpcGasLimit`, `accountGasLimit`, `maxCalldataBytes` and
-`maxSimulationGas` tighten admission when supplied. Missing policy remains explicit in
-`limits.unknownExecutionConstraints`/`unknownConstraints`; it does not reject an otherwise
-proved exact sequence or invent a provider/account cap. No policy service is required.
+Optional `chainGasLimit`, `rpcGasLimit`, `accountGasLimit` and `maxCalldataBytes`
+tighten admission. `maxSimulationGas` sets the aggregate used-gas proof-window
+budget (default 50M on 4663, unknown on other chains). Missing policy stays explicit
+in `limits.unknownExecutionConstraints`/`unknownConstraints`; no policy service is required.
 A `LifecycleLimitSource` callback receives the canonical chain/account/core/block context.
 Any supplied provenance must match it; stale/mismatched/malformed facts or a failed supplied
 resolver reject rather than disappearing into optional uncertainty. Gas caps are positive
@@ -897,7 +1077,9 @@ exact uint64 `bigint`; calldata is a positive safe integer byte count.
 Reviewed gas envelopes are positive uint64 too; zero-metering observations cannot admit
 a zero-gas transaction. Headroom calculations retain wide exact bigint intermediates.
 
-Headroom defaults to 1,500 bps, bounded 0–10,000. Generic EVM admission uses the pinned
+Headroom defaults to 1,500 bps, bounded 0–10,000; it clamps to current legal ceilings
+instead of rejecting a fitting measured requirement. HMM V2 adds the forwarding
+target documented above once on atomic/activation. Generic EVM admission uses the pinned
 bounded header and supplied total-envelope restrictions plus actual validated RPC proof.
 It reports an absent independent per-transaction cutoff honestly, without importing a
 universal Ethereum cutoff. `executionGasCeiling` and `transactionGasCeiling` are equal on
@@ -910,8 +1092,8 @@ carries that successfully replayed ceiling, never a smaller unproved envelope.
 Replay source, HTTP and malformed-response failures remain provisional with
 `executionProof: "unavailable"` and do not retry economic execution. `AbortError`
 propagates unchanged, including cancellation during supplied policy and Nitro getter
-reads. A recognized execution refusal may discover at most one genuinely larger
-validated envelope within the same legal compute/total limits. Without returned
+reads. Only explicit genuine native out-of-gas evidence may discover at most one
+larger validated envelope within the same legal compute/total limits. Without returned
 failing-call evidence, `failedTransactionId` stays absent; an opaque RPC error does
 not invent a failing transaction or authorize preparation partitioning.
 Returned failures retain the actual exact-replay prefix and its first failing
@@ -949,10 +1131,10 @@ The buffered compute-discovery envelope plus buffered poster budget is carried i
 exact validated replay; an approximate poster quote is never subtracted from total
 gas use to certify exact compute fit.
 Measurement waits for successful capability and candidate-specific poster evidence,
-then uses the legal complete compute-plus-poster envelope. Near-cap gas consumption
-does not diagnose OOG, constructor failure or collision. Unsupported/transport
-evidence remains unavailable, and only a recognized execution-envelope refusal
-can trigger bounded envelope discovery.
+then uses the legal complete compute-plus-poster envelope. A packed preparation
+failure consuming at least 95% may invalidate its cost estimate without claiming
+its selector diagnoses OOG. Unsupported/transport evidence remains unavailable,
+except an observed aggregate-budget exhaustion can preserve a successful prefix.
 
 A separate pinned validated simulation probes all three ArbOS/version/getter values
 against the canonical observations. Only that isolated capability probe temporarily
@@ -975,13 +1157,13 @@ does not manufacture an all-in estimate. All observations and limits refresh for
 For initial construction, the exact legacy gas-price envelope is the greater of
 the fresh RPC recommendation and twice the pinned base fee. This avoids
 underpriced submission when `eth_gasPrice` lags the block base fee. Reviewed
-envelopes retain their exact gas/price only after fresh full-sequence measurement,
-native validated replay, current minimum headroom and affordability checks.
+envelopes retain exact gas/price through direct immediate native validated replay
+and immediate affordability, without repeating measurement or applying new padding.
 The held price need not equal a new recommendation or twice the current base fee;
 natural child fees and the actual submission estimate must accept it. Replay,
 affordability and submission use that same price, without a base-fee override.
-A known aggregate budget whose legal minimum already exceeds its ceiling refuses
-before capability probes or poster work; equality is allowed. A definitive returned
+An aggregate budget selects the longest fitting estimated prefix; only when even
+the immediate estimate does not fit is no proof possible. A definitive returned
 failure from the final exact replay skips a later payer-balance lookup, while
 retaining fee/estimate validation and final canonical checks. Successful replay
 still requires current actual-balance affordability.
@@ -1013,14 +1195,15 @@ Simulation and `next.admission` carry flat, independent proof outcomes:
 
 | Field | Values | Scope |
 | --- | --- | --- |
-| `executionProof` | `"proved"`, `"failed"`, `"unavailable"` | Complete stateful exact-envelope execution and postconditions, never permissive measurement alone. |
+| `executionProof` | `"proved"`, `"failed"`, `"unavailable"` | Stateful exact-envelope execution/postconditions for the proven prefix (or the immediate reviewed step), never measurement alone or an unproved suffix. |
 | `protocolFit` | `"proved"`, `"failed"`, `"unknown"` | Applicable proven protocol and known tightening restrictions. Missing optional policy remains separately disclosed. |
 | `transportPreflight` | `"not-requested"`, `"passed"`, `"failed"` | Immediate exact next-transaction acceptance estimate on the supplied submission RPC. |
 
-`admitted` means the current exact sequence is proved to fit and affordable; it is
-not guaranteed wallet submission or future execution. Admission reuses simulation
-`blockNumber`, `blockHash`, `account`, `chainId` and `limits`. Plans never preflight
-future dependent transactions against state that does not exist.
+`admitted` means the proven prefix fits and is affordable, not that deferred
+transactions have executed or that eventual activation is guaranteed. Always
+inspect `simulation.deferredTransactionIds`. Admission reuses `blockNumber`,
+`blockHash`, `account`, `chainId` and `limits`; signing uses only fresh build-next
+admission. Plans never preflight future steps independently against nonexistent state.
 
 ```ts
 const planned = await planLaunch({ client, account: plan.creator, plan, mode: "atomic" });

package/examples/.env.example

@@ -35,3 +35,7 @@ NFT_BASE_URI=
 # EXAMPLE_ACCOUNT_GAS_CAP=
 # EXAMPLE_MAX_CALLDATA_BYTES=
 # EXAMPLE_HEADROOM_BPS=1500
+#
+# Robinhood aggregate simulation gas-used budget defaults to 50M. Override only for
+# a provider supporting that budget; buy-output calibration needs activation coverage.
+# EXAMPLE_SIMULATION_GAS_CAP=100000000

package/examples/README.md

@@ -1,8 +1,8 @@
 # Examples
 
-The launch examples use the public `@black-market/sdk` 0.9.0 package and viem.
+The launch examples use the public `@black-market/sdk` 0.12.0 package and viem.
 Build this checkout before running its examples; in a consumer project install
-`@black-market/sdk@0.8.0` or later for the `positionGaps` and recovery APIs.
+`@black-market/sdk@0.12.0` for opt-in UFG treasuries and current proof semantics.
 The default chain-4663 launch cases retain
 the October8 mined fixed pool-bound V4 config6/V2 and canonical Abyss config1 deployment.
 The SDK additionally knows the October11 zero-author-royalty Dynamic Fee Hook;
@@ -25,11 +25,25 @@ examples; their relative support imports use explicit `.ts` extensions for Node
 | --- | --- |
 | `quickstart.ts` | Reads the current mainnet orchestrator, checks its registry binding, and discovers admitted profiles. No wallet or writes. |
 | `hmm-launch-config.ts` | Pure HMM V2 fixed/dynamic config construction with caller-chosen bid/reference guards and an automatically appended 512-byte launch tail; no RPC, signatures or writes. |
+| `ufg-launch-config.ts` | Pure fixed/dynamic UFG quote-only config6 construction, canonical reserve tail and config hash; no RPC, wallet or writes. |
 | `launch.ts` | Reviews/reconstructs an explicit saved plan and selected atomic/staged mode; optional offchain config6/V2 salt mining. Prints simulation, progress, and an admitted unsigned next transaction when evidence permits. |
 | `generate-lifecycle-commitment-fixture.ts` | Frozen independent historical config4/Abyss ABI bytes/hash/identity vector. Its pre-cutover allocations are not an executable 0.7.1 plan. |
 | `launch-lifecycle-smoke.ts` | Actual SDK launch/recovery/custody/fee operations, only on an explicitly authorized owned disposable loopback graph. |
 | `launch-erc20-*.ts`, `launch-erc404-*.ts` | Eleven independent fixed cases: unsigned end-to-end planning by default; `--broadcast` adds guarded local signing, chain verification and mandatory API publication/indexing. |
 
+## UFG treasury configuration
+
+Run `pnpm build && node examples/ufg-launch-config.ts` for a pure consumer example.
+Real UFG plans use the proxy as creator and a principal-namespaced nonce, with
+`ufg: { config }` on `prepareAndPlanLifecycleLaunch`; the principal remains the
+planning/signing account. Use only reward-free ERC20, full treasury reserve share,
+launch-token burn policies, Abyss QUOTE/QUOTE_ORACLE or the UFG fixed/dynamic
+presets. Approvals go to the proxy. The existing eleven launch cases and their
+selected non-UFG offerings are intentionally unchanged.
+
+The opt-in owned-fork regression is `test/integration/ufg-launch.fork.mjs`; see the
+[lifecycle guide](../docs/launch-lifecycle.md#ufg-owned-fork-check).
+
 ## Deployed read-only discovery
 
 ```sh
@@ -73,6 +87,18 @@ generic EVM, not as a Nitro metering substitute. Unsigned review reports
 RPC to build-next. See the
 [lifecycle guide](../docs/launch-lifecycle.md#execution-constraints-and-stateful-simulation).
 
+Robinhood defaults to a 50M aggregate simulation gas-used budget. Inspect
+`simulation.deferredTransactionIds`: admitted/proved means the proven prefix,
+not every future transaction or eventual activation. Deferred commands have no
+gas/price/estimate/admission; obtain each fresh immediate envelope through
+`buildNextTransaction` after canonical progress advances. Reviewed envelopes are
+replayed directly, without measuring/replaying the suffix again. The saved-plan
+CLI prints proof coverage and never signs. Override `limits.maxSimulationGas` only
+for a provider that supports the selected budget. Examples requiring actual
+activation outputs for `buySlippageBps` or economic review refuse if activation is
+deferred; use a suitably higher-budget provider rather than inventing buy outputs.
+
+
 For a real new graph, create the saved plan using `readLifecycleProfiles` with its
 explicit chain/core and admitted pool-bound config6 profile. Supply that graph's RPC
 to `launch.ts`; do not substitute the historical known preset. Applications may use
@@ -381,6 +407,13 @@ to tighten the complete transaction envelope: `EXAMPLE_CHAIN_GAS_CAP`,
 restrictions, not invented provider/account assurances or admission bypasses.
 Poster allocation is already inside Nitro gas/affordability and is not charged twice.
 
+Robinhood's separate aggregate simulation gas-used budget defaults to **50M**.
+`EXAMPLE_SIMULATION_GAS_CAP` overrides that budget (positive decimal gas) for
+providers supporting more or less. It does not change per-transaction compute
+capacity. Multi-step examples requiring full activation outputs for buy protection
+and economic review need a provider/budget covering activation, or refuse before
+signing; do not raise the setting beyond the provider's actual supported budget.
+
 ### Evidence and failure recovery
 
 Each dry run or broadcast automatically creates `launch-results/<timestamp-case-random>/`;

package/examples/launch-example-support.ts

@@ -540,6 +540,7 @@ export async function readExampleConfiguration(sdk, redactor, env = process.env)
       chainTransactionGasLimit: gasCap("EXAMPLE_CHAIN_GAS_CAP"),
       rpcTransactionGasLimit: gasCap("EXAMPLE_RPC_GAS_CAP"),
       accountTransactionGasLimit: gasCap("EXAMPLE_ACCOUNT_GAS_CAP"),
+      rpcTotalSimulationGasLimit: gasCap("EXAMPLE_SIMULATION_GAS_CAP"),
       maxCalldataBytes: integer("EXAMPLE_MAX_CALLDATA_BYTES", undefined, 1, Number.MAX_SAFE_INTEGER),
       headroomBps: integer("EXAMPLE_HEADROOM_BPS", 1500, 0, 10000),
       provenance: { scope: "user-ceilings", note: "Optional local tightening restrictions, not verified provider or account limits" },

package/examples/launch-example.ts

@@ -477,6 +477,7 @@ function limitSource(fixture, artifacts) {
       chainGasLimit: policy.chainTransactionGasLimit === undefined ? undefined : BigInt(policy.chainTransactionGasLimit),
       rpcGasLimit: policy.rpcTransactionGasLimit === undefined ? undefined : BigInt(policy.rpcTransactionGasLimit),
       accountGasLimit: policy.accountTransactionGasLimit === undefined ? undefined : BigInt(policy.accountTransactionGasLimit),
+      maxSimulationGas: policy.rpcTotalSimulationGasLimit === undefined ? undefined : BigInt(policy.rpcTotalSimulationGasLimit),
       maxCalldataBytes: policy.maxCalldataBytes, headroomBps: policy.headroomBps,
     };
     artifacts.event("execution-limits", { limits, provenance: policy.provenance });

package/examples/launch.ts

@@ -30,6 +30,7 @@ const options = { client, account: plan.creator, plan, mode, limits, fork, recei
 const planned = args.includes("--mine")
   ? await prepareAndPlanLifecycleLaunch({ ...options, onProgress: ({ marketIndex, attempts }) => console.error("salt mining", marketIndex, attempts.toString()) })
   : await planLaunch(options);
+console.error("Proof coverage:", planned.simulation.steps.length, "steps; deferred:", planned.simulation.deferredTransactionIds);
 const progress = await readLaunchProgress({ client, planned, receipts, confirmations });
 const next = planned.simulation.admitted ? await buildNextTransaction({ client, planned, limits, fork, receipts, confirmations }) : undefined;
 console.log(JSON.stringify({ plan: JSON.parse(serializeLaunchPlan(planned.plan)), mode,

package/examples/ufg-launch-config.ts

@@ -0,0 +1,31 @@
+// Pure configuration example; no RPC, wallet, key, signing or broadcast.
+// This is not a priced/admitted plan. Use core.predictToken(plan) for real fee policies,
+// derive funded one-sided positions, then prepareAndPlanLifecycleLaunch({ ..., ufg: { config } }).
+import { encodeAbiParameters, keccak256, zeroHash } from "viem";
+import {
+  getAddresses, KnownLifecycleProfile, getKnownLifecycleProfile,
+  UFG_ORCHESTRATOR_ADDRESS, UFG_LAUNCH_PROXY_ADDRESS, encodeUfgLaunchConfig,
+  hashUfgLaunchConfig, encodePoolBoundV4LifecycleMarketConfig,
+} from "@black-market/sdk";
+
+const identity = { chainId: 4663n, orchestrator: UFG_ORCHESTRATOR_ADDRESS };
+const config = { treasuryShareBps: 10000, exitFeeBps: 100, reserveAssets: [getAddresses(4663).weth] };
+for (const key of [KnownLifecycleProfile.V4UfgFixedPool, KnownLifecycleProfile.V4UfgDynamicPool]) {
+  const preset = getKnownLifecycleProfile({ ...identity, key })!;
+  const envelope = preset.profile.envelope!;
+  const encoded = encodePoolBoundV4LifecycleMarketConfig({
+    version: 6, lpFeePips: 0, tickSpacing: 60, sqrtPriceX96: 1n << 96n,
+    hookFeePips: 10000, minimumHookFeePips: 1000, feeSensitivityPipsSecondsPerTick: 7654321,
+    feeMode: 1, protocolFeeDenominator: envelope.protocolFeeDenominator,
+    treasury: envelope.protocolTreasury, externalLiquidityDisabled: false,
+    oracleConfigId: keccak256(encodeAbiParameters([{ type: "uint24" }, { type: "uint16" }], [1, 4096])),
+    hookSalt: zeroHash, profileId: preset.profile.id, termsDigest: envelope.termsDigest,
+    developerBeneficiary: envelope.beneficiary, developerFeeBps: 0,
+    // Geometry/price are illustrative. Real launch uses predicted token ordering and budget-funded ranges.
+    positions: [{ tickLower: 0, tickUpper: 887220, liquidity: 1000n, salt: zeroHash, maxTokenAmount: 1000000n }],
+    ufgLaunchConfig: config,
+  });
+  console.log(key, { proxy: UFG_LAUNCH_PROXY_ADDRESS, profileId: preset.profile.id,
+    configBytes: (encoded.length - 2) / 2, tailBytes: (encodeUfgLaunchConfig(config).length - 2) / 2,
+    launchConfigHash: hashUfgLaunchConfig(config) });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "TypeScript SDK for Abyss token launches, swaps, and lending.",
   "license": "MIT",
   "repository": {

package/src/lifecycle/abi.ts

@@ -6,6 +6,7 @@ import {
 } from "./schema.js";
 import { poolBoundHookParametersV1Components, poolBoundHookParametersV2Components, v4LifecycleMarketComponents } from "./markets.js";
 export { hmmLiquidityManagerV2Abi, hmmFeeCollectorV2Abi, hmmFeeCollectorFactoryV2Abi, hmmFixedHookV2Abi, hmmDynamicHookV2Abi } from "./hmm-abi.js";
+export { ufgLaunchProxyV1Abi, ufgTreasuryFactoryV1Abi, ufgBlackMarketFactoryAbi, ufgBlackMarketTreasuryAbi } from "./ufg-abi.js";
 
 const planInput = { name: "plan", type: "tuple", components: launchPlanV1Components } as const;
 export const launchLifecycleAbi = [