@artblocks/abx-sdk 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/ops.d.ts

@@ -1,5 +1,5 @@
-import { type Address, type Hex } from 'viem';
-import type { OneOfOneInitParams, SeriesCodeInitParams, SeriesInitParams } from './deploy.js';
+import { type Address, type Hex, type PublicClient } from 'viem';
+import type { EditionCodeInitParams, EditionImageInitParams, OneOfOneEditionInitParams, OneOfOneInitParams, SeriesCodeInitParams, SeriesInitParams } from './deploy.js';
 /**
  * An unsigned, ready-to-sign transaction — the SDK's neutral output for every
  * write. It carries only the data needed to sign (`to`/`data`/`value`/`chainId`)
@@ -17,6 +17,20 @@ export interface PreparedTx {
     chainId: number;
     summary: string;
     fields: Record<string, string>;
+    /**
+     * A **provable** lower bound on this tx's gas — a value the real cost cannot possibly be below.
+     *
+     * This is a DETECTOR, not a substitute gas limit. It exists because `eth_estimateGas` can return a
+     * confidently wrong answer (an estimate taken against a target whose code isn't visible yet is
+     * just the calldata cost), and the only safe response to a wrong estimate is to notice and refuse
+     * — not to invent a replacement number. A sender treats `estimate < gasFloor` as "this estimate is
+     * impossible", retries, and errors out; it does NOT send `gasFloor` instead, because a bound that
+     * covers the provable part says nothing about the rest of the payload.
+     *
+     * Set it only from costs that are physics rather than guesswork. The one such cost here is EVM
+     * code deposit: storing N bytes on-chain costs exactly 200·N gas, before any other work.
+     */
+    gasFloor?: Hex;
 }
 /**
  * Batch several ops into ONE atomic transaction via the target's
@@ -46,6 +60,11 @@ export declare function prepareMulticall(args: {
  * preserved — important when a later op depends on an earlier one's effect — so a run is
  * only merged while the target stays the same. This is what turns "6 owner edits" into
  * "1 transaction" for the UX, while staying honest about what genuinely needs its own tx.
+ *
+ * A CREATE2-proxy deploy (`to === CREATE2_PROXY` — the renderer/minter/seed-source singletons)
+ * is creation too, even though it carries a `to`: the proxy has no `multicall`, so folding two of
+ * them together would silently produce a transaction that reverts on the target it's actually
+ * sent to. Excluded from merging for the same reason `to === null` is.
  */
 export declare function batchOps(ops: PreparedTx[]): PreparedTx[];
 /** Transfer a token to a new holder (a sale/gift settlement). Signer must be `from`. */
@@ -66,6 +85,37 @@ export declare function prepareMint(args: {
     to: Address;
     chainId: number;
 }): PreparedTx;
+/**
+ * The token ids a mint actually created, decoded from its receipt's mint logs — `Transfer` from
+ * `0x0` on a 721 token, or `TransferSingle`/`TransferBatch` from `0x0` on an edition (each id
+ * reported once, regardless of how many copies it minted — an edition amount has nowhere to ride
+ * in a `string[]`, so it's a job for the sibling {@link mintedEditionAmounts}). Both event
+ * families are probed unconditionally (harmless — a contract only ever emits the one that
+ * matches its own standard, so exactly one probe ever finds anything) rather than branching on
+ * contract type, so this stays a single call for either kind.
+ *
+ * Authoritative by construction: the ids come from the transaction that minted them, so a
+ * `--count N` batch reports all N and a concurrent mint elsewhere cannot skew the answer. Returns
+ * `[]` rather than throwing if the receipt can't be read — a mint that landed on-chain must not be
+ * reported as failed because a follow-up read hiccuped.
+ */
+export declare function mintedTokenIds(client: PublicClient, contract: Address, txHash: Hex): Promise<string[]>;
+/** One id's minted copy count from a single edition mint transaction — the amount half {@link
+ *  mintedTokenIds} can't carry (its `string[]` shape is shared with the 721 side, where a token
+ *  is always exactly 1 unit). */
+export interface MintedEditionAmount {
+    tokenId: string;
+    amount: string;
+}
+/**
+ * The `(id, amount)` pairs an edition mint actually created, decoded from its receipt's
+ * `TransferSingle`/`TransferBatch` (`from == 0x0`) logs — the amount-carrying sibling of {@link
+ * mintedTokenIds}, for callers that need "how many copies of #7 did this tx mint" rather than
+ * just "which ids." Amounts are summed per id (a batch could in principle mint the same id
+ * twice in one call), then sorted by id. Returns `[]` on a 721 receipt (no matching events) or
+ * any read failure, same fail-open contract as {@link mintedTokenIds}.
+ */
+export declare function mintedEditionAmounts(client: PublicClient, contract: Address, txHash: Hex): Promise<MintedEditionAmount[]>;
 /** Re-point a token's resolver BASE (move the resolver). The per-token pointer is derived
  *  on-chain as `{base}/{chainId}/{address}/{tokenId}`. Affects every token without an
  *  override. Signer must be the owner. */
@@ -124,11 +174,40 @@ export declare function prepareLockContractURI(args: {
     chainId: number;
 }): PreparedTx;
 /** Set the contract-wide default royalty. Signer must be the owner. */
+/**
+ * The on-chain royalty ceiling, mirrored from `RoyaltyExtension._maxRoyaltyBps()` (1000 bps = 10%).
+ *
+ * Client-side validation used to allow the full 0–10000 ERC-2981 range, and the CLI's own error text
+ * offered `10000 = 100%` as an example — so a creator asking for an ordinary 15% got a fully built,
+ * fully signed transaction that reverted `RoyaltyTooHigh()` on chain. On the wallet lane they approved
+ * it in their own wallet first and paid the gas to find out. Validate against the real cap so the
+ * refusal is instant, local and free.
+ *
+ * The royalty ceiling is now **per-collection**: owner-set at deploy (0–10000 bps) and reduce-only
+ * after. So this constant is the ABSOLUTE protocol maximum (100%); a collection's own, possibly
+ * lower, `maxRoyaltyBps()` is the binding cap and is enforced on chain. To refuse an over-cap
+ * `set-royalty` instantly rather than after a revert, pass `maxBps` (the collection's live cap, read
+ * from `maxRoyaltyBps()`); it defaults to the absolute max when omitted.
+ */
+export declare const MAX_ROYALTY_BPS = 10000;
 export declare function prepareSetRoyalty(args: {
     contract: Address;
     receiver: Address;
     bps: number;
     chainId: number;
+    maxBps?: number;
+}): PreparedTx;
+/**
+ * Lower a collection's royalty ceiling (`RoyaltyExtension.reduceMaxRoyaltyBps`). Owner-only and
+ * **reduce-only**: the chain reverts `RoyaltyCapNotReduced()` if `newMaxBps` is not strictly below
+ * the current cap, and `RoyaltyCapBelowRoyalty()` if it would sit under the live royalty rate. This
+ * builder is domain-only (0–100%); the CLI reads the live cap + rate to refuse both cases before
+ * signing so the failure is local and free rather than a paid revert. Emits `MaxRoyaltyBpsUpdated`.
+ */
+export declare function prepareReduceMaxRoyaltyBps(args: {
+    contract: Address;
+    newMaxBps: number;
+    chainId: number;
 }): PreparedTx;
 /**
  * Set/replace an on-chain metadata field for a token. `field` is what (e.g. "image",
@@ -185,11 +264,19 @@ export declare function prepareDeployOneOfOne(args: {
     chainId: number;
     clone: Address;
 }): PreparedTx;
-/** 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 declare function prepareDeployFactory(args: {
     chainId: number;
 }): PreparedTx;
-/** The unsigned form of the canonical metadata-renderer deploy — a contract creation. */
+/** The unsigned form of the canonical metadata-renderer deploy — CREATE2 via the keyless proxy +
+ *  canonical salt, so it lands at the SAME (predictable) address on every chain, matching the forge
+ *  `DeployRenderer` script and `predictRenderer()` (create2.ts). NOT a plain contract creation
+ *  (`to: null`) — that would land at a nonce-dependent address, defeating the whole point of a
+ *  canonical, cross-chain-identical singleton. */
 export declare function prepareDeployRenderer(args: {
     chainId: number;
 }): PreparedTx;
@@ -245,10 +332,111 @@ export declare function prepareDeploySeries(args: {
     chainId: number;
     clone: Address;
 }): PreparedTx;
-/** 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 declare function prepareDeploySeriesFactory(args: {
     chainId: number;
 }): PreparedTx;
+/**
+ * Mint `amount` copies of `id` to `to` (`IAbxEditionMint.mint`). Owner always; the authorized
+ * minter only while unpaused — same auth shape as {@link prepareMint}/{@link prepareSeriesMint}.
+ * The edition twin of both: there is no separate "next in order" primitive here, since an
+ * edition mint always names its id.
+ */
+export declare function prepareEditionMint(args: {
+    contract: Address;
+    to: Address;
+    tokenId: bigint | number;
+    amount: bigint | number;
+    chainId: number;
+}): PreparedTx;
+/** Transfer `amount` copies of `id` to a new holder (`safeTransferFrom(from,to,id,amount,"")` on
+ *  the ERC-1155 ABI) — the edition twin of {@link prepareTransfer}. Signer must be `from` (or an
+ *  operator it approved via the standard `setApprovalForAll`). */
+export declare function prepareEditionTransfer(args: {
+    contract: Address;
+    from: Address;
+    to: Address;
+    tokenId: bigint | number;
+    amount: bigint | number;
+    chainId: number;
+}): PreparedTx;
+/**
+ * Owner overrides `id`'s supply cap (Edition Supply extension) — the edition twin of {@link
+ * prepareSetMaxInvocations}, one id finer. Monotonically non-increasing once used for this id,
+ * never below its live `totalSupply(id)` (see `IAbxEditionSupply`'s "0 = open until overridden"
+ * semantics — an explicit `0` permanently closes the id, it does not mean "reopen to uncapped").
+ * Signer must be the owner.
+ */
+export declare function prepareSetMaxSupply(args: {
+    contract: Address;
+    tokenId: bigint | number;
+    cap: bigint | number;
+    chainId: number;
+}): PreparedTx;
+/**
+ * Permissionless, caller-chunked re-emission of the native `URI` event for the given ids —
+ * called after a contract-wide re-point (`setTokenURIBase`/`setTokenURIRenderer`, which emit
+ * only their own Register-2 config event; see `Uri1155`'s class-level dev note on why there's no
+ * automatic per-id loop for that case) to make marketplaces/indexers that only honor the native
+ * event re-index. Anyone may call it — it only re-emits already-public, current truth, so there
+ * is no state to protect; the caller picks the batch size.
+ */
+export declare function preparePingURI(args: {
+    contract: Address;
+    tokenIds: Array<bigint | number>;
+    chainId: number;
+}): PreparedTx;
+/** The unsigned form of a 1/1-edition genesis deploy — `deployDeterministic(params, salt)` on
+ *  the {@link oneOfOneEditionFactoryAbi} factory. The edition twin of {@link
+ *  prepareDeployOneOfOne}. */
+export declare function prepareDeployOneOfOneEdition(args: {
+    factory: Address;
+    params: OneOfOneEditionInitParams;
+    salt: Hex;
+    chainId: number;
+    clone: Address;
+}): PreparedTx;
+/** 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.
+ *
+ *  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 declare function prepareDeployOneOfOneEditionFactory(args: {
+    chainId: number;
+}): PreparedTx;
+/** The unsigned form of an edition-image genesis deploy — `deployDeterministic(params, salt)` on
+ *  the {@link editionImageFactoryAbi} factory. The edition twin of {@link prepareDeploySeries}. */
+export declare function prepareDeployEditionImage(args: {
+    factory: Address;
+    params: EditionImageInitParams;
+    salt: Hex;
+    chainId: number;
+    clone: Address;
+}): PreparedTx;
+/** 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, and {@link
+ *  prepareDeployOneOfOneEditionFactory} for why the initcode is linked against `AbxEditionLib`
+ *  (`EditionImage` delegates the same three mixins' bodies into it). */
+export declare function prepareDeployEditionFactory(args: {
+    chainId: number;
+}): PreparedTx;
+/** Deterministic deploy of an {EditionCode} clone — the code-project edition factory op. The
+ *  edition twin of {@link prepareDeploySeriesCode}. */
+export declare function prepareDeployEditionCode(args: {
+    factory: Address;
+    params: EditionCodeInitParams;
+    salt: Hex;
+    chainId: number;
+    clone: Address;
+}): PreparedTx;
 /**
  * Set/update a project's fixed-price sale on the shared minter. Signer must be the ABX
  * token's owner. `paymentToken == 0x0` prices the sale in ETH; otherwise it's that ERC-20.
@@ -264,23 +452,219 @@ export declare function prepareConfigureSale(args: {
     allocation: bigint | number;
     chainId: number;
 }): PreparedTx;
+/** The sale terms a buyer is agreeing to — the input to the minter's on-chain terms guard.
+ *  ("Terms guard", not "slippage guard": on the ETH lane it tolerates no movement at all — see
+ *  {@link preparePurchase}.)
+ *  A {@link SaleConfig} (or {@link SaleConfig1155}) read from the chain drops straight in, which is
+ *  the point: the terms that go into the transaction are the terms the caller just read. */
+export type PurchaseTerms = Pick<SaleConfig, 'paymentToken' | 'price'>;
 /**
  * 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 declare function preparePurchase(args: {
     minter: Address;
     token: Address;
+    sale: PurchaseTerms;
     to?: Address;
-    value?: bigint | number;
+    maxPrice?: bigint | number;
+    chainId: number;
+}): PreparedTx;
+/** A project's fixed-price sale state on the shared minter (`sales(token)`): whether a sale is
+ *  configured, the payment token (`zeroAddress` = ETH), the per-unit price, the minter's own
+ *  sell-through budget (`allocation`, distinct from the token's `maxInvocations` cap), and units
+ *  sold so far. The read half of {@link prepareConfigureSale}/{@link preparePurchase} — every
+ *  caller that needs to know a sale's live terms (show it, gate a purchase) reads through here. */
+export interface SaleConfig {
+    configured: boolean;
+    paymentToken: Address;
+    price: bigint;
+    allocation: bigint;
+    sold: bigint;
+}
+export declare function readSaleConfig(client: PublicClient, minter: Address, token: Address): Promise<SaleConfig>;
+/** The unsigned form of the shared fixed-price minter deploy — CREATE2 via the keyless proxy +
+ *  canonical salt (same address on every chain), matching `predictFixedPriceMinter()`. See
+ *  {@link prepareDeployRenderer} for why this is `to: CREATE2_PROXY`, not a plain creation. */
+export declare function prepareDeployFixedPriceMinter(args: {
     chainId: number;
 }): PreparedTx;
-/** The unsigned form of the shared fixed-price minter deploy — a contract creation. */
-export declare function prepareDeployFixedPriceMinter(args: {
+/**
+ * Set/update a project's fixed-price sale for one id on the shared edition minter. The id-keyed
+ * twin of {@link prepareConfigureSale}. Signer must be the ABX token's owner.
+ */
+export declare function prepareConfigureSale1155(args: {
+    minter: Address;
+    token: Address;
+    tokenId: bigint | number;
+    paymentToken?: Address;
+    price: bigint | number;
+    allocation: bigint | number;
+    chainId: number;
+}): PreparedTx;
+/**
+ * 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 declare function preparePurchase1155(args: {
+    minter: Address;
+    token: Address;
+    tokenId: bigint | number;
+    quantity: bigint | number;
+    sale: PurchaseTerms;
+    to?: Address;
+    maxTotalPrice?: bigint | number;
+    chainId: number;
+}): PreparedTx;
+/** A project's fixed-price sale state for one id on the shared edition minter (`sales(token,
+ *  id)`) — the id-keyed twin of {@link SaleConfig}. */
+export interface SaleConfig1155 {
+    configured: boolean;
+    paymentToken: Address;
+    price: bigint;
+    allocation: bigint;
+    sold: bigint;
+}
+/** The id-keyed twin of {@link readSaleConfig}. */
+export declare function readSaleConfig1155(client: PublicClient, minter: Address, token: Address, tokenId: bigint | number): Promise<SaleConfig1155>;
+/** The unsigned form of the shared edition minter deploy — CREATE2 via the keyless proxy +
+ *  canonical salt (same address on every chain), matching `predictFixedPriceMinter1155()`. See
+ *  {@link prepareDeployRenderer} for why this is `to: CREATE2_PROXY`, not a plain creation. */
+export declare function prepareDeployFixedPriceMinter1155(args: {
     chainId: number;
 }): PreparedTx;
+/** The unsigned form of the canonical seed source deploy — CREATE2 via the keyless proxy +
+ *  canonical salt (same address on every chain), matching `predictSeedSource()`. See
+ *  {@link prepareDeployRenderer} for why this is `to: CREATE2_PROXY`, not a plain creation. */
+export declare function prepareDeploySeedSource(args: {
+    chainId: number;
+}): PreparedTx;
+/**
+ * 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 declare function prepareSetSeedSource(args: {
+    contract: Address;
+    seedSource: Address;
+    chainId: number;
+}): PreparedTx;
+/**
+ * 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 declare function readSeedSource(client: PublicClient, contract: Address): Promise<Address | undefined>;
+/**
+ * Why a candidate seed source is unusable — or `ok`. Structured rather than a sentence: the SDK
+ * doesn't know a UX's flag names (see `AnchorUnavailableError`'s note), so the caller composes the
+ * guidance and this only says which shape it hit.
+ *
+ *   - `no-code`      — nothing deployed there. A Solidity call to a codeless address SUCCEEDS with
+ *                      zero returndata, so the token's `abi.decode` to `bytes32` is what reverts.
+ *   - `empty-return` — has code, answered, returned nothing. The permissive-fallback shape: a
+ *                      **Safe** (`FallbackManager.fallback()` returns empty for an unset handler),
+ *                      an uninitialised proxy, an EIP-7702-delegated EOA. Same mint revert.
+ *   - `short-return` — answered with fewer than 32 bytes; not a `bytes32` no matter what it is.
+ *   - `reverted`     — has code and refused the call. Either the wrong address entirely (a token,
+ *                      a renderer — no such selector, no fallback) or a real source that is gating
+ *                      callers / not yet armed. Both are refusals: `seed()` is called
+ *                      **synchronously inside the mint** and its revert bubbles, so a source that
+ *                      cannot answer now cannot answer at mint either.
+ *   - `unreachable`  — the RPC didn't answer. Says nothing about the address; retry, don't refuse
+ *                      on the merits (a preview may choose to defer the check and say so).
+ */
+export type SeedSourceVerdict = 'ok' | 'no-code' | 'empty-return' | 'short-return' | 'reverted' | 'unreachable';
+/** The result of {@link probeSeedSource} — the verdict plus what was observed, for a message. */
+export interface SeedSourceProbe {
+    verdict: SeedSourceVerdict;
+    /** The address probed. */
+    address: Address;
+    /** Bytes of returndata, when the call answered at all (`ok`/`empty-return`/`short-return`). */
+    returnedBytes?: number;
+    /** First line of the revert/transport error, for `reverted` / `unreachable`. */
+    error?: string;
+}
+/**
+ * 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 declare function probeSeedSource(client: PublicClient, source: Address, opts?: {
+    as?: Address;
+    tokenId?: bigint;
+}): Promise<SeedSourceProbe>;
+/**
+ * {@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 declare function assertSeedSourceUsable(client: PublicClient, source: Address, opts?: {
+    as?: Address;
+    tokenId?: bigint;
+}): Promise<void>;
 /** Deterministic deploy of a {SeriesCode} clone — the code-project factory op. */
 export declare function prepareDeploySeriesCode(args: {
     factory: Address;
@@ -298,6 +682,8 @@ export declare function prepareCodeSetup(args: {
     chainId: number;
     chunkCount: number;
     schemaKeys: string[];
+    /** Byte length of each script chunk this multicall stores. Used only to compute `gasFloor`. */
+    chunkBytes?: number[];
     deps?: string[];
     onchainUri?: boolean;
 }): PreparedTx;
@@ -329,10 +715,21 @@ export declare function prepareLockDependencies(args: {
     contract: Address;
     chainId: number;
 }): PreparedTx;
+/** 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 declare function prepareLockScript(args: {
+    contract: Address;
+    chainId: number;
+}): PreparedTx;
 /** 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 `params.keys` / `display.gateway`.
- *  Signer must be the owner. */
+ *  the write behind well-known contract params like `display.animation`. The key joins the
+ *  contract's on-chain key list automatically (`contractParamKeys`), so it is enumerated by
+ *  the generator and the renderer with no separate declaration. Signer must be the owner. */
 export declare function prepareSetContractParam(args: {
     contract: Address;
     key: string;
@@ -351,7 +748,15 @@ export declare 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 declare function prepareSetParamHooks(args: {
     contract: Address;
     configureHook: Address;
@@ -359,6 +764,42 @@ export declare function prepareSetParamHooks(args: {
     transferHook: Address;
     chainId: number;
 }): PreparedTx;
+/**
+ * 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 declare function readParamHooksLocked(client: PublicClient, contract: Address): Promise<boolean | 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 declare function prepareLockParamHooks(args: {
+    contract: Address;
+    chainId: number;
+}): PreparedTx;
 /** Set a schema-governed PostParam (literal scalar) — signer must satisfy the schema's auth. */
 export declare function prepareConfigureTokenParam(args: {
     contract: Address;
@@ -376,4 +817,56 @@ export declare function prepareConfigureTokenParamData(args: {
     data: Hex;
     chainId: number;
 }): PreparedTx;
+/** Attach or replace one key's schema. Owner-only.
+ *
+ *  A replacement does NOT re-validate values already stored under the key — narrow a bound, drop a
+ *  `Select` option or change the type and existing tokens keep values that now violate their own
+ *  schema. Callers that are editing (rather than creating) should read the current schema first and
+ *  carry forward every field they don't mean to change; this is a full-row write, not a patch. */
+export declare function prepareSetParamSchema(args: {
+    contract: Address;
+    key: string;
+    paramType: number;
+    auth: number;
+    authAddress?: Address;
+    lockAfter?: number;
+    min: Hex;
+    max: Hex;
+    selectOptions?: string[];
+    chainId: number;
+    /** Human rendering for the sign page (the CLI's `describeSchema`). */
+    display?: string;
+}): PreparedTx;
+/** The decoded on-chain schema for one key (`paramSchema(bytes32)`). `exists: false` ⇒ ungoverned. */
+export interface OnChainParamSchema {
+    exists: boolean;
+    paramType: number;
+    auth: number;
+    authAddress: Address;
+    lockAfter: number;
+    min: Hex;
+    max: Hex;
+    selectOptions: string[];
+}
+/** Read one key's schema from chain. The read half of the upsert — anything editing a live schema
+ *  MUST start here, or it silently rewrites the fields it didn't mention. */
+export declare function readParamSchema(client: PublicClient, contract: Address, key: string): Promise<OnChainParamSchema>;
+/**
+ * Retire a parameter: keep every field of its existing schema and set only `lockAfter` to a past
+ * timestamp, so all further writes revert `ParamLockExpired`. This is the closest thing the protocol
+ * has to deleting a parameter, and it is the read-modify-write case the upsert makes dangerous —
+ * hence the caller passes the schema it just READ, rather than a schema it composed.
+ *
+ * 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 creator should not be able to delete someone else's contribution.
+ */
+export declare function prepareRetireParam(args: {
+    contract: Address;
+    key: string;
+    current: OnChainParamSchema;
+    chainId: number;
+    /** Unix seconds; defaults to "one second ago" (already expired ⇒ permanent). */
+    at?: number;
+}): PreparedTx;
 //# sourceMappingURL=ops.d.ts.map