@artblocks/abx-sdk 0.1.0-alpha.13 → 0.1.0-alpha.14

package/dist/ops.js

@@ -1,7 +1,10 @@
 import { encodeFunctionData, parseEventLogs, toHex, zeroAddress } from 'viem';
-import { oneOfOneImageAbi, oneOfOneImageFactoryAbi, oneOfOneImageFactoryBytecode, seriesImageAbi, seriesImageFactoryAbi, seriesImageFactoryBytecode, abxMetadataRendererBytecode, abxFixedPriceMinterAbi, abxFixedPriceMinterBytecode, abxFixedPriceMinter1155Abi, abxFixedPriceMinter1155Bytecode, abxSeedSourceBytecode, seriesCodeAbi, seriesCodeFactoryAbi, oneOfOneEditionAbi, oneOfOneEditionFactoryAbi, oneOfOneEditionFactoryBytecode, editionImageFactoryAbi, editionImageFactoryBytecode, editionCodeFactoryAbi, } from './abi/index.js';
+import { oneOfOneImageAbi, oneOfOneImageFactoryAbi, seriesImageAbi, seriesImageFactoryAbi, abxMetadataRendererBytecode, abxFixedPriceMinterAbi, abxFixedPriceMinterBytecode, abxFixedPriceMinter1155Abi, abxFixedPriceMinter1155Bytecode, abxSeedSourceAbi, abxSeedSourceBytecode, seriesCodeAbi, seriesCodeFactoryAbi, oneOfOneEditionAbi, oneOfOneEditionFactoryAbi, editionImageFactoryAbi, editionCodeFactoryAbi, } from './abi/index.js';
 import { encodeTag } from './spine.js';
-import { ABX_SALT, CREATE2_PROXY, create2Calldata } from './create2.js';
+import { SeedSourceUnusableError } from './errors.js';
+// The two edition-image factories are library-linked, so their initcode comes from the `link*`
+// helpers, never from the raw `*Bytecode` exports (which still carry solc's `__$…$__` placeholder).
+import { ABX_SALT, CREATE2_PROXY, create2Calldata, linkEditionFactory, linkFactory, linkOneOfOneEditionFactory, linkSeriesFactory, } from './create2.js';
 const ZERO_VALUE = '0x0';
 function short(addr) {
     return addr.length > 12 ? `${addr.slice(0, 6)}…${addr.slice(-4)}` : addr;
@@ -470,12 +473,16 @@ export function prepareDeployOneOfOne(args) {
         },
     };
 }
-/** The unsigned form of the factory (trust-anchor) deploy — a contract creation. */
+/** The unsigned form of the factory (trust-anchor) deploy — CREATE2 via the keyless proxy at the
+ *  canonical salt, matching the forge `Deploy` script and `predictFactory()` (create2.ts). A trust
+ *  anchor is the one address platforms allowlist, so it has to be the same on every chain and
+ *  computable before the first tx; a plain creation (`to: null`) would make it depend on the
+ *  deployer's nonce and could never match the recorded manifest. */
 export function prepareDeployFactory(args) {
     return {
         op: 'deploy-factory',
-        to: null,
-        data: oneOfOneImageFactoryBytecode,
+        to: CREATE2_PROXY,
+        data: create2Calldata(ABX_SALT.oneOfOneFactory, linkFactory()),
         value: ZERO_VALUE,
         chainId: args.chainId,
         summary: 'Deploy the canonical clone factory (trust anchor)',
@@ -610,12 +617,14 @@ export function prepareDeploySeries(args) {
         },
     };
 }
-/** The unsigned form of the Series factory (trust-anchor) deploy — a contract creation. */
+/** The unsigned form of the Series factory (trust-anchor) deploy — CREATE2 via the keyless proxy at
+ *  the canonical salt, matching the forge `DeploySeries` script and `predictSeriesFactory()`. Same
+ *  reasoning as `prepareDeployFactory` above. */
 export function prepareDeploySeriesFactory(args) {
     return {
         op: 'deploy-series-factory',
-        to: null,
-        data: seriesImageFactoryBytecode,
+        to: CREATE2_PROXY,
+        data: create2Calldata(ABX_SALT.seriesFactory, linkSeriesFactory()),
         value: ZERO_VALUE,
         chainId: args.chainId,
         summary: 'Deploy the canonical Series clone factory (trust anchor)',
@@ -625,7 +634,7 @@ export function prepareDeploySeriesFactory(args) {
 // ── ERC-1155 editions (IAbxEditionMint + Edition Supply) ──────────────────────
 // Ids are caller-named, not a sequential cursor — a minter/owner targets any id, in any order,
 // with a per-mint amount. `mint`'s signature is uniform across all three edition kinds
-// (`OneOfOneEdition` reverts unless `id === 0`, its id space fixed to the single artwork), so
+// (`OneOfOneEdition` reverts unless `id === 0`, its id space fixed to the single work), so
 // every op below encodes against `oneOfOneEditionAbi` — the narrowest-common-superset ABI for
 // the family, exactly like `oneOfOneImageAbi` plays that role on the 721 side.
 /**
@@ -734,15 +743,21 @@ export function prepareDeployOneOfOneEdition(args) {
 /** The unsigned form of the 1/1-edition factory (trust-anchor) deploy — CREATE2 via the keyless
  *  proxy + canonical salt, so it lands at the SAME (predictable) address on every chain, matching
  *  `predictOneOfOneEditionFactory()` (create2.ts). See {@link prepareDeployRenderer} for why this
- *  is `to: CREATE2_PROXY`, not a plain creation. */
+ *  is `to: CREATE2_PROXY`, not a plain creation.
+ *
+ *  The initcode goes out LINKED against `AbxEditionLib` (`linkOneOfOneEditionFactory()`): the
+ *  embedded `OneOfOneEdition` implementation delegates its uri / creator-token / edition-supply
+ *  bodies into that library, so the shipped bytecode carries a solc `__$…$__` placeholder. That
+ *  library must already be on-chain at `predictEditionLib()` for the deployed factory to work —
+ *  {@link deployOneOfOneEditionFactory} (deploy.ts) is the path that guarantees it. */
 export function prepareDeployOneOfOneEditionFactory(args) {
     return {
         op: 'deploy-one-of-one-edition-factory',
         to: CREATE2_PROXY,
-        data: create2Calldata(ABX_SALT.oneOfOneEditionFactory, oneOfOneEditionFactoryBytecode),
+        data: create2Calldata(ABX_SALT.oneOfOneEditionFactory, linkOneOfOneEditionFactory()),
         value: ZERO_VALUE,
         chainId: args.chainId,
-        summary: 'Deploy the canonical 1/1-edition clone factory (trust anchor) — CREATE2, deterministic address',
+        summary: 'Deploy the canonical 1/1-edition clone factory (trust anchor), linked against AbxEditionLib — CREATE2, deterministic address',
         fields: {},
     };
 }
@@ -772,15 +787,17 @@ export function prepareDeployEditionImage(args) {
 }
 /** The unsigned form of the edition-image factory (trust-anchor) deploy — CREATE2 via the
  *  keyless proxy + canonical salt, matching `predictEditionFactory()` (create2.ts). See {@link
- *  prepareDeployRenderer} for why this is `to: CREATE2_PROXY`, not a plain creation. */
+ *  prepareDeployRenderer} for why this is `to: CREATE2_PROXY`, not a plain creation, and {@link
+ *  prepareDeployOneOfOneEditionFactory} for why the initcode is linked against `AbxEditionLib`
+ *  (`EditionImage` delegates the same three mixins' bodies into it). */
 export function prepareDeployEditionFactory(args) {
     return {
         op: 'deploy-edition-factory',
         to: CREATE2_PROXY,
-        data: create2Calldata(ABX_SALT.editionFactory, editionImageFactoryBytecode),
+        data: create2Calldata(ABX_SALT.editionFactory, linkEditionFactory()),
         value: ZERO_VALUE,
         chainId: args.chainId,
-        summary: 'Deploy the canonical multi-artwork edition clone factory (trust anchor) — CREATE2, deterministic address',
+        summary: 'Deploy the canonical multi-work edition clone factory (trust anchor), linked against AbxEditionLib — CREATE2, deterministic address',
         fields: {},
     };
 }
@@ -846,25 +863,68 @@ export function prepareConfigureSale(args) {
 }
 /**
  * Buy one token from the shared minter. `to` omitted → minted to the signer (`purchase`);
- * `to` set → minted to that address (`purchaseTo`). `value` is the ETH to attach (equal to
- * the sale price for an ETH sale; `0` for an ERC-20 sale, where the buyer must have approved
- * the minter to pull `price` beforehand). Public — no owner rights needed.
+ * `to` set → minted to that address (`purchaseTo`). Public — no owner rights needed.
+ *
+ * `sale` is the live terms ({@link readSaleConfig}), and they are **mandatory**: the minter takes
+ * `(expectedPaymentToken, maxPrice)` and reverts `SaleTermsChanged` if the sale has moved, which is
+ * what stops a project owner from front-running a pending purchase and spending the buyer's whole
+ * ERC-20 allowance (`configure` has no timelock). The ETH to attach is derived from those terms —
+ * `price` for an ETH sale, `0` for an ERC-20 one (where the buyer must have approved the minter to
+ * pull `price` beforehand) — so a caller can't desync the payment from the guard.
+ *
+ * `maxPrice` defaults to `sale.price` (accept exactly what was read). Pass it to state a wider
+ * ceiling. It bounds the guard only; the ETH attached still comes from `sale.price`, since the minter
+ * wants exact payment. There is deliberately no "no maximum" sentinel.
+ *
+ * **A wide `maxPrice` is how a caller opts out of the protection.** The minter refuses a sentinel
+ * precisely so that a bound has to be stated, but nothing stops a caller from stating an enormous
+ * one — and on the ERC-20 lane that hands back exactly the vector the guard closes: the minter pulls
+ * the live price from the buyer's standing allowance, so a ceiling of `2^256-1` lets a re-priced sale
+ * take the whole allowance. Omitting the argument is the safe path and is what every caller in this
+ * repo does. If you widen it, widen it by an amount you would be content to lose, and never derive it
+ * from a price you read in the same breath as sending — that is the same thing as no bound at all.
+ *
+ * **On the ETH lane, `maxPrice` is a terms ASSERTION, not slippage tolerance — do not sell it as
+ * one.** The minter requires `msg.value == price` (an equality) and V1 has no refund path, so an
+ * in-flight ETH purchase reverts `WrongPayment` if the price moves in *either* direction, however
+ * wide the ceiling. Raising `maxPrice` on an ETH sale buys the buyer nothing at all. Real tolerance
+ * exists only on the **ERC-20** lane, where the minter pulls the live `price` from the buyer's
+ * allowance and any price at or below the ceiling settles. Re-pricing a live ETH sale therefore fails
+ * every buy already in flight, by design — pause first for a clean cutover.
  */
 export function preparePurchase(args) {
-    const value = BigInt(args.value ?? 0n);
+    const paymentToken = args.sale.paymentToken;
+    const price = BigInt(args.sale.price);
+    const isEth = paymentToken === zeroAddress;
+    const maxPrice = args.maxPrice === undefined ? price : BigInt(args.maxPrice);
+    const value = isEth ? price : 0n; // exact payment; an ERC-20 sale attaches none
     const toRecipient = args.to && args.to !== zeroAddress;
+    const cost = isEth ? `${price} wei` : `${price} units of ${short(paymentToken)}`;
     return {
         op: 'purchase',
         to: args.minter,
         data: toRecipient
-            ? encodeFunctionData({ abi: abxFixedPriceMinterAbi, functionName: 'purchaseTo', args: [args.token, args.to] })
-            : encodeFunctionData({ abi: abxFixedPriceMinterAbi, functionName: 'purchase', args: [args.token] }),
+            ? encodeFunctionData({
+                abi: abxFixedPriceMinterAbi,
+                functionName: 'purchaseTo',
+                args: [args.token, args.to, paymentToken, maxPrice],
+            })
+            : encodeFunctionData({
+                abi: abxFixedPriceMinterAbi,
+                functionName: 'purchase',
+                args: [args.token, paymentToken, maxPrice],
+            }),
         value: value > 0n ? toHex(value) : ZERO_VALUE,
         chainId: args.chainId,
-        summary: toRecipient
-            ? `Buy 1 token → ${short(args.to)}${value > 0n ? ` for ${value} wei` : ''}`
-            : `Buy 1 token${value > 0n ? ` for ${value} wei` : ''}`,
-        fields: { minter: args.minter, token: args.token, to: args.to ?? '(sender)', value: value.toString() },
+        summary: toRecipient ? `Buy 1 token → ${short(args.to)} for ${cost}` : `Buy 1 token for ${cost}`,
+        fields: {
+            minter: args.minter,
+            token: args.token,
+            to: args.to ?? '(sender)',
+            value: value.toString(),
+            expectedPaymentToken: paymentToken,
+            maxPrice: maxPrice.toString(),
+        },
     };
 }
 export async function readSaleConfig(client, minter, token) {
@@ -892,7 +952,7 @@ export function prepareDeployFixedPriceMinter(args) {
 }
 // ── Fixed-price EDITION minter (the Minter spine's 1155 lane) ────────────────
 // The structural sibling of the block above, keyed one step finer: `(token, id)` instead of just
-// `token`, since an edition project prices each artwork on its own terms. See
+// `token`, since an edition project prices each work on its own terms. See
 // `AbxFixedPriceMinter1155`'s own doc comment for the two-grant model (mint rights via
 // `setMinter`, sale terms via `configure` — unchanged from the 721 lane, one id finer).
 /**
@@ -930,23 +990,44 @@ export function prepareConfigureSale1155(args) {
  * Buy `quantity` copies of `id` from the shared edition minter. The id/quantity-keyed twin of
  * {@link preparePurchase}. `to` omitted → minted to the signer (`purchase`); `to` set → minted to
  * that address (`purchaseTo`). Public — no owner rights needed.
+ *
+ * `sale` is the live terms ({@link readSaleConfig1155}) and is mandatory, same terms guard as the 721
+ * lane — except the minter bounds the **total** (`price × quantity`), which is what actually leaves
+ * the buyer's balance. `price × quantity` is computed here (once), for both the attached ETH and the
+ * bound; `maxTotalPrice` defaults to it, and passing it states a wider ceiling.
+ *
+ * The ETH-lane caveat on {@link preparePurchase} applies here identically: `msg.value` must equal the
+ * total exactly, so `maxTotalPrice` is an assertion about the terms, **not** slippage tolerance. Only
+ * an ERC-20 edition sale gets real tolerance.
  */
 export function preparePurchase1155(args) {
     const id = BigInt(args.tokenId);
     const qty = BigInt(args.quantity);
-    const value = BigInt(args.value ?? 0n);
+    const paymentToken = args.sale.paymentToken;
+    const total = BigInt(args.sale.price) * qty;
+    const isEth = paymentToken === zeroAddress;
+    const maxTotalPrice = args.maxTotalPrice === undefined ? total : BigInt(args.maxTotalPrice);
+    const value = isEth ? total : 0n; // exact payment; an ERC-20 sale attaches none
     const toRecipient = args.to && args.to !== zeroAddress;
+    const cost = isEth ? `${total} wei` : `${total} units of ${short(paymentToken)}`;
+    const copies = `${qty} cop${qty === 1n ? 'y' : 'ies'} of #${id}`;
     return {
         op: 'purchase',
         to: args.minter,
         data: toRecipient
-            ? encodeFunctionData({ abi: abxFixedPriceMinter1155Abi, functionName: 'purchaseTo', args: [args.token, id, qty, args.to] })
-            : encodeFunctionData({ abi: abxFixedPriceMinter1155Abi, functionName: 'purchase', args: [args.token, id, qty] }),
+            ? encodeFunctionData({
+                abi: abxFixedPriceMinter1155Abi,
+                functionName: 'purchaseTo',
+                args: [args.token, id, qty, args.to, paymentToken, maxTotalPrice],
+            })
+            : encodeFunctionData({
+                abi: abxFixedPriceMinter1155Abi,
+                functionName: 'purchase',
+                args: [args.token, id, qty, paymentToken, maxTotalPrice],
+            }),
         value: value > 0n ? toHex(value) : ZERO_VALUE,
         chainId: args.chainId,
-        summary: toRecipient
-            ? `Buy ${qty} cop${qty === 1n ? 'y' : 'ies'} of #${id} → ${short(args.to)}${value > 0n ? ` for ${value} wei` : ''}`
-            : `Buy ${qty} cop${qty === 1n ? 'y' : 'ies'} of #${id}${value > 0n ? ` for ${value} wei` : ''}`,
+        summary: toRecipient ? `Buy ${copies} → ${short(args.to)} for ${cost}` : `Buy ${copies} for ${cost}`,
         fields: {
             minter: args.minter,
             token: args.token,
@@ -954,6 +1035,8 @@ export function preparePurchase1155(args) {
             quantity: qty.toString(),
             to: args.to ?? '(sender)',
             value: value.toString(),
+            expectedPaymentToken: paymentToken,
+            maxTotalPrice: maxTotalPrice.toString(),
         },
     };
 }
@@ -995,6 +1078,118 @@ export function prepareDeploySeedSource(args) {
         fields: {},
     };
 }
+// ── the seed source (Seed Source extension, Register 2) ───────────────────────
+// Mint-time randomness is CONFIGURATION, not hard-coded token logic: the token holds one address
+// and calls `IAbxSeedSource.seed(tokenId, to)` on it at mint. The canonical `AbxSeedSource` is
+// deliberately pseudorandom (replayable after the fact, computable *during* the mint tx), so the
+// documented escape for anything lottery-like is to point this at a commit-reveal / VRF-backed
+// source of the project's own. That promise is only real if a creator can actually SET the address
+// — which is what the two ops below, plus the probe, exist for.
+/**
+ * Set (or clear, with `0x0`) the seed source a code project draws mint seeds from. Signer must be
+ * the owner. **Future mints only** — a seed is settled once assigned, so re-pointing never rewrites
+ * a token that already has one.
+ *
+ * Pass an address that {@link probeSeedSource} says is usable. The chain does NOT validate the
+ * source (`SeedSourceExtension.setSeedSource` stores whatever it's handed), and the failure mode of
+ * a bad one is the worst kind: `seedSource()` reads back exactly what you set, the `SeedSourceSet`
+ * event fires, everything looks configured — and then every mint reverts in the ABI decode of the
+ * source's (empty or short) return. Callers should probe first and refuse before gas.
+ */
+export function prepareSetSeedSource(args) {
+    const clearing = args.seedSource === zeroAddress;
+    return {
+        op: 'set-seed-source',
+        to: args.contract,
+        data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'setSeedSource', args: [args.seedSource] }),
+        value: ZERO_VALUE,
+        chainId: args.chainId,
+        summary: clearing
+            ? 'Clear the seed source (future mints draw no seed; assigned seeds stay settled)'
+            : `Set seed source → ${short(args.seedSource)} (future mints only)`,
+        fields: { contract: args.contract, seedSource: args.seedSource },
+    };
+}
+/**
+ * The seed source a token currently draws from — `zeroAddress` for "no mint-time seed", and
+ * `undefined` when the getter isn't there at all (a 1/1 or an image Series never composed the
+ * extension). Those two are NOT the same fact and must not be collapsed: one is a code project
+ * that opted out, the other is a token that has no such knob to set.
+ */
+export async function readSeedSource(client, contract) {
+    return (await client
+        .readContract({ address: contract, abi: seriesCodeAbi, functionName: 'seedSource' })
+        .catch(() => undefined));
+}
+/**
+ * Ask a candidate seed source the exact question the token will ask it, and report whether it
+ * answers with 32 bytes.
+ *
+ * **`code.length > 0` is not enough**, which is the whole reason this exists. Three separate shapes
+ * pass a has-code check, read back correctly from `seedSource()`, emit `SeedSourceSet`, and then
+ * revert **every mint of the collection**: no code, a permissive fallback that returns empty (a
+ * Safe, an uninitialised proxy, a 7702-delegated EOA — the same footgun the transfer-validator
+ * probe in `CreatorToken.sol` was written for), and anything answering with fewer than 32 bytes.
+ * A misconfigured seed source is silent until the first buyer, so the check belongs at configure
+ * time, loudly.
+ *
+ * `IAbxSeedSource.seed` is **non-`view`** (sources may keep state — commit-reveal, oracle-fed), but
+ * an `eth_call` simulates a state-changing function perfectly well and the canonical implementation
+ * is itself `view`, so one `eth_call` probes both kinds without sending anything.
+ *
+ * The call is made **as the token** (`from` = `opts.as`, when given): `msg.sender` namespaces the
+ * canonical seed and is exactly what a caller-gating custom source checks, so probing from a
+ * random address would false-negative a legitimate source. Same reason the transfer-validator
+ * research used `cast call --from <collection>`.
+ *
+ * Never throws for an on-chain reason — every failure is a verdict.
+ */
+export async function probeSeedSource(client, source, opts = {}) {
+    let code;
+    try {
+        code = await client.getCode({ address: source });
+    }
+    catch (err) {
+        return { verdict: 'unreachable', address: source, error: firstLine(err) };
+    }
+    if (!code || code === '0x')
+        return { verdict: 'no-code', address: source };
+    const tokenId = opts.tokenId ?? 0n;
+    // `to` mirrors the mint: the token asks for a seed for a recipient. The canonical source ignores
+    // it; a custom one may not, so pass a plausible non-zero address rather than 0x0 (which a source
+    // validating its recipient would rightly refuse, turning a good source into a false negative).
+    const to = opts.as ?? source;
+    try {
+        const res = await client.call({
+            to: source,
+            data: encodeFunctionData({ abi: abxSeedSourceAbi, functionName: 'seed', args: [tokenId, to] }),
+            ...(opts.as ? { account: opts.as } : {}),
+        });
+        const bytes = res.data ? (res.data.length - 2) / 2 : 0;
+        if (bytes === 0)
+            return { verdict: 'empty-return', address: source, returnedBytes: 0 };
+        if (bytes < 32)
+            return { verdict: 'short-return', address: source, returnedBytes: bytes };
+        return { verdict: 'ok', address: source, returnedBytes: bytes };
+    }
+    catch (err) {
+        return { verdict: 'reverted', address: source, error: firstLine(err) };
+    }
+}
+/** First line of an error message — a revert reason is readable; viem's full dump is not. */
+function firstLine(err) {
+    return String(err?.message ?? err).split('\n')[0].trim();
+}
+/**
+ * {@link probeSeedSource}, as a guard: throws {@link SeedSourceUnusableError} unless the verdict is
+ * `ok`. For an SDK caller that just wants "refuse a bad source" without composing prose; the CLI
+ * uses the probe directly so it can name its own flags in the refusal.
+ */
+export async function assertSeedSourceUsable(client, source, opts = {}) {
+    const probe = await probeSeedSource(client, source, opts);
+    if (probe.verdict !== 'ok')
+        throw new SeedSourceUnusableError(probe);
+}
 /** Deterministic deploy of a {SeriesCode} clone — the code-project factory op. */
 export function prepareDeploySeriesCode(args) {
     return {
@@ -1129,6 +1324,23 @@ export function prepareLockDependencies(args) {
         fields: { contract: args.contract },
     };
 }
+/** Freeze the on-chain program (script chunks) forever — `setScriptChunk`/`removeLastScriptChunk`
+ *  revert after this. Irreversible, owner-only. This is the lock that actually freezes the WORK
+ *  of a code project; `lock-field`/`lock-uri` only freeze the metadata, and `lock-dependencies` only
+ *  the library set. All of them together freeze everything the CONTRACT stores — which is not the
+ *  same as a frozen output: params have no lock and the renderer serves them, and a `Registry`
+ *  dependency resolves from the registry at read time. */
+export function prepareLockScript(args) {
+    return {
+        op: 'lock-script',
+        to: args.contract,
+        data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'lockScript', args: [] }),
+        value: ZERO_VALUE,
+        chainId: args.chainId,
+        summary: 'Freeze the on-chain program (script chunks) — permanent',
+        fields: { contract: args.contract },
+    };
+}
 /** Set a CONTRACT-scope param to a literal `bytes32` (the raw owner setter — Params base).
  *  Only for schema-less keys (a schema'd key closes the raw path: `SchemaGoverned`). This is
  *  the write behind well-known contract params like `display.gateway`. The key joins the
@@ -1169,7 +1381,15 @@ export function prepareSetContractParamData(args) {
 /** Wire the three param-lifecycle hook addresses (configure/augment/transfer) in ONE owner call.
  *  The contract has no per-hook setter — `setParamHooks` writes all three at once — so a caller
  *  changing one hook must pass the CURRENT values for the other two (read them via `paramHooks()`),
- *  else it silently clears them. `zeroAddress` for any role means "no hook". SeriesCode only. */
+ *  else it silently clears them. `zeroAddress` for any role means "no hook". SeriesCode/EditionCode
+ *  only.
+ *
+ *  Note what the `transferHook` slot is: a **veto**. Its revert bubbles and fails the transfer, and
+ *  a mint is a transfer from `0x0`, so a reverting hook stops minting for the project too. Setting
+ *  one is therefore a standing power over a collector's ability to sell — disclose it, and offer
+ *  {@link prepareLockParamHooks} to a project that wants to prove it will never arm one.
+ *
+ *  Reverts `ParamHooksLocked()` once {@link prepareLockParamHooks} has been sent. */
 export function prepareSetParamHooks(args) {
     return {
         op: 'set-param-hooks',
@@ -1190,6 +1410,60 @@ export function prepareSetParamHooks(args) {
         },
     };
 }
+/**
+ * Is the param hook set frozen (`lockParamHooks()` already sent)?
+ *
+ * One `eth_call` to `paramHooksLocked()`. This used to simulate `setParamHooks` as the owner and
+ * watch for a `ParamHooksLocked()` revert, on the stated grounds that no getter existed — it does
+ * now (`IAbxConfigurableParams`), and the simulation cost two extra reads (`paramHooks` + `owner`)
+ * to infer what one read states.
+ *
+ * The other honest read is the `ParamHooksFrozen` event, which is what `reconstructProject` folds
+ * (`ProjectState.paramHooks.locked`). Prefer the fold when you already have the logs; use this when
+ * you have an address and one RPC round trip, which is `abx state`'s situation.
+ *
+ * Returns `undefined` — never throws for an on-chain reason — when the answer can't be established:
+ * not a ConfigurableParams project, or the node refused the call. A caller must render that as
+ * "unknown", never as "unlocked".
+ */
+export async function readParamHooksLocked(client, contract) {
+    try {
+        return (await client.readContract({
+            address: contract,
+            abi: seriesCodeAbi,
+            functionName: 'paramHooksLocked',
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Freeze the param-lifecycle hook set forever — `setParamHooks` reverts `ParamHooksLocked()` after
+ * this. Irreversible, owner-only. The sibling of `lock-script`/`lock-dependencies`/`lock-uri`, and
+ * the one aimed at a **buyer** rather than at the metadata: the `transferHook` is a veto (its revert
+ * fails a transfer, and a mint is a transfer from `0x0`), so while the hooks are unwritten-in-stone a
+ * project retains a standing power over whether a collector can ever sell. Sending this gives up
+ * three abilities permanently — arming a transfer veto, arming a write-time configure veto, and
+ * re-pointing or clearing the read-time augment hook — and it cannot be undone, re-opened, or
+ * time-limited. A project that never wants the power sends it before the sale; a buyer reads
+ * `paramHooks()` plus the `ParamHooksFrozen` event (`abx state`) to check.
+ *
+ * It does NOT freeze anything else: schemas, values, script, dependencies, and URIs all keep their
+ * own locks, and a hook already set keeps running exactly as before — freezing the SET is not
+ * disarming the hooks in it.
+ */
+export function prepareLockParamHooks(args) {
+    return {
+        op: 'lock-param-hooks',
+        to: args.contract,
+        data: encodeFunctionData({ abi: seriesCodeAbi, functionName: 'lockParamHooks', args: [] }),
+        value: ZERO_VALUE,
+        chainId: args.chainId,
+        summary: 'Freeze the param hooks (configure/augment/transfer) — permanent',
+        fields: { contract: args.contract },
+    };
+}
 /** Set a schema-governed PostParam (literal scalar) — signer must satisfy the schema's auth. */
 export function prepareConfigureTokenParam(args) {
     return {
@@ -1284,7 +1558,7 @@ export async function readParamSchema(client, contract, key) {
  *
  * What retiring does NOT do: erase a value already stored. That value keeps being served in token
  * data. It cannot be removed, deliberately — a value written under a `TokenOwner` or `Address` leg
- * came from a collector, and the artist should not be able to delete someone else's contribution.
+ * came from a collector, and the creator should not be able to delete someone else's contribution.
  */
 export function prepareRetireParam(args) {
     const lockAfter = args.at ?? Math.floor(Date.now() / 1000) - 1;