websitekit

API reference

Every export of @websitekit/sdk — 189 of them, across 10 groups — and 137 more from its image-board entry point, @websitekit/sdk/image-boards. This page is generated from the package’s own type declarations at build time, so it cannot describe a function that does not exist, miss one that does, or show a signature the compiler disagrees with.

The grouping and the section notes come from the SDK’s entry points, which is where the API is deliberately ordered for a reader. § references point into the protocol spec, and under image boards into the image-board spec.

Install @websitekit/sdk, or read the source.

Pricing

the shared math, byte-identical to Pricing.sol (§4).

BPS_DENOMINATORconst
10000n

The TypeScript twin of `packages/websitekit-contracts/src/Pricing.sol`.

BuyBreakdowninterface
interface BuyBreakdown extends TakeQuote, Split {}
computeBuyBreakdownfunction
(lastPrice: bigint, basePrice: bigint, elapsedWeeks: bigint, economics: SiteEconomics, isUnclaimed: boolean) => BuyBreakdown

What a buy costs and where the money goes, composed from the same two primitives `SlotSite._buy` composes and in the same order. This is what a confirm dialog should render — one call, so a UI cannot show a price derived one way and a payout derived another.

computeElapsedWeeksfunction
(nowTs: bigint, lastPurchaseTs: bigint) => bigint

Mirrors `SlotSite._computeElapsedWeeks`. Truncates toward zero, which equals floor because both operands are non-negative. The contract's `uint256` subtraction reverts on underflow; this throws for the same input rather than returning a negative week count that would run the loop zero times and quietly quote the undecayed price.

computeSplitfunction
(effectiveFloor: bigint, price: bigint, isUnclaimed: boolean, payoutBps: bigint, protocolBps: bigint) => Split

Mirrors `Pricing.computeSplit`. Every leg is keyed to `effectiveFloor`, never to `charged` or to a stale `lastPrice` — a displaced owner is paid against what the slot is worth now, not against what they happened to pay for it.

computeTakePricefunction
(lastPrice: bigint, basePrice: bigint, elapsedWeeks: bigint, decayBps: bigint, takeBps: bigint, maxDecayWeeks: bigint) => TakeQuote

Mirrors `Pricing.computeTakePrice`.

PricingOverflowErrorclass
typeof PricingOverflowError

Thrown where Solidity's checked arithmetic would revert. Distinct from `RangeError` so a caller can tell "this input overflows the chain's word size" from "you passed a negative week count", and never silently caught alongside ordinary validation errors.

SECONDS_PER_WEEKconst
604800n
SiteEconomicsinterface
interface SiteEconomics { takeBps: bigint; payoutBps: bigint; reversionBps: bigint; maxReversionWeeks: bigint; protocolBps: bigint; }

A site's take economics, in the SDK's own vocabulary.

Splitinterface
interface Split { /** The effective floor on a claim, the take price on a take. This is what `lastPrice` records. */ charged: bigint; /** To the displaced owner. `0n` on a claim; there is nobody to pay. */ payout: bigint; /** To the protoco…
TakeQuoteinterface
interface TakeQuote { /** What a taker pays to displace the current owner. */ price: bigint; /** `max(decayed, basePrice)` — what a first claim pays, and what the whole split is keyed to. */ effectiveFloor: bigint; }

The ask

the reversion BASE an owner posts, not a list price (§3).

askCeilingfunction
(lastPrice: bigint, basePrice: bigint, maxAskBps: bigint) => bigint

Mirrors `Pricing.askCeiling` — spec §3.2. The highest ask an owner may post.

resolveReversionBasefunction
(askFloor: bigint, lastPrice: bigint) => bigint

Mirrors `Pricing.resolveReversionBase` — spec §3.

Rent

accrual, the unaccrued remainder a buyer inherits, and the fee split (§2).

accrualfunction
(prepaid: bigint, start: bigint, expiry: bigint, nowTs: bigint) => Accrual

Both legs at once. Prefer this to calling `accruedOf` and subtracting by hand: the identity `accrued + unaccrued === prepaid` holds exactly, and computing the two independently is how a caller ends up rendering a total that does not add up.

Accrualinterface
interface Accrual { /** Rent the owner has earned so far, whether or not it has been claimed. */ accrued: bigint; /** * The part of the escrow not yet earned — **what a buyer inherits.** * * §2.4.2 calls surfacing this the single highest-va…
accruedOffunction
(prepaid: bigint, start: bigint, expiry: bigint, nowTs: bigint) => bigint

Mirrors `RentalsLib.accruedOf`. Linear accrual over the term, with no segment history — which is what lets `extendRental` settle and restart with a single formula instead of a schedule.

MIN_RENTAL_DURATIONconst
3600n

The shortest term the contract will open or extend (§2.5.3).

quoteRentfunction
(ratePerDay: bigint, durationSecs: bigint, protocolRentBps: bigint, feeBps: bigint) => RentQuote
rentCostfunction
(ratePerDay: bigint, durationSecs: bigint) => bigint

Mirrors `RentalsLib.rentCost`. Gross rent for a term.

RentQuoteinterface
interface RentQuote extends RentSplit { /** Gross, and what the tenant is actually charged. */ cost: bigint; }

What a tenant pays and where it goes, composed the way `SlotSite.rent` composes it.

rentSplitfunction
(cost: bigint, protocolRentBps: bigint, feeBps: bigint) => RentSplit

Mirrors `RentalsLib.rentSplit` — spec §2.5.

RentSplitinterface
interface RentSplit { /** To the protocol treasury. */ protocolCut: bigint; /** To the site's treasury, at the rate snapshotted on the listing when it was written. */ siteCut: bigint; /** Escrowed, and streamed to whoever owns the position …
SECONDS_PER_DAYconst
86400n

Seconds in a day. Rent rates are quoted per day; durations are in seconds (§2.5.3).

Content addressing

sha256([version][kind][payload]), the hash is the CID (§3).

cidBytesToStringfunction
(cid: Hex) => string

Any binary CID — `0x01…`, a CIDv1 of any codec — as its base32 string (`b…`). An image board's source picture is too large for one raw block, so its address is a CID of its own rather than its hash (`IMAGE-BOARD-SPEC.md` §13.7); this is how a reader writes it. The same encoder as `contentHashToCid`, which is this applied to the raw-block prefix and the hash.

cidToContentHashfunction
(cid: string) => Hex

The inverse. Useful for checking that a gateway URL a site has stored actually addresses the hash the chain holds — the two can drift, and when they do the slot renders someone else's content with no error.

ContentFailuretype
type ContentFailure = /** The bytes do not hash to what the chain says. Never render these. */ | 'hash-mismatch' /** Shorter than the header, or a kind of 0. */ | 'malformed' /** Verified, but written under a scheme this package does not kn…
contentHashToCidfunction
(hash: Hex) => string

Renders a `bytes32` content hash as the IPFS CIDv1 raw block that addresses the same bytes.

ContentKindtype
ContentKind = { Text: 1, Link: 2, Image: 3, Video: 4, /** * A body of some other kind, with a destination attached — see `encodeLinked`. * * **A wrapper rather than a product type**, because the decision it encodes was *a link is * optional…

Well-known payload kinds. `kind` is a `u8` and the framework claims only the low range; ids from `SITE_DEFINED_KIND_MIN` up are yours and will never be assigned a meaning here.

ContentResulttype
type ContentResult = | ({ ok: true } & DecodedContent) | { ok: false; reason: ContentFailure; schemeVersion?: number };
ContentTooLargeErrorclass
typeof ContentTooLargeError
decodeContentfunction
(bytes: Uint8Array) => DecodedContent

Splits an object into its header and payload. Does NOT verify the hash — use `readContent` for anything that will be rendered.

DecodedContentinterface
interface DecodedContent { schemeVersion: number; kind: number; payload: Uint8Array; }
DecodedLinkedinterface
interface DecodedLinked { /** The kind of the body — never `Linked`, never `Text`, never `Link`. */ innerKind: number; /** Where it points, exactly as written. **Scheme policy is the renderer's**, not this function's. */ href: string; /** T…
decodeLinkedfunction
(payload: Uint8Array) => DecodedLinked

Reads a `Linked` payload back. Throws `MalformedContentError` on anything a renderer should treat as fallback — a truncated header, a length that runs past the end, a body kind that may not be wrapped, or a href that is not UTF-8.

encodeContentfunction
(kind: number, payload: Uint8Array) => EncodedContent

Wraps a payload in the scheme header and hashes it.

EncodedContentinterface
interface EncodedContent { /** The full object — this is what gets stored, and what the hash is taken over. */ bytes: Uint8Array; /** `sha256(bytes)`, the value written on-chain. */ hash: Hex; /** The same hash expressed as an IPFS CIDv1 ra…
encodeImagefunction
(bytes: Uint8Array) => EncodedContent
encodeLinkedfunction
(innerKind: number, href: string, body: Uint8Array) => EncodedContent

Wraps a body of another kind with a destination.

encodeTextfunction
(text: string) => EncodedContent

UTF-8 bytes, unsanitized and unescaped — see the module note on why that is correct here.

HEADER_BYTESconst
2

The header is two bytes: `[schemeVersion][kind]`.

MalformedContentErrorclass
typeof MalformedContentError
MAX_OBJECT_BYTESconst
1048576

**Enforced at encode time, so it bites before anyone signs.**

readContentfunction
(bytes: Uint8Array, expectedHash: Hex) => ContentResult

The one function a renderer should call. Verify, then decode, in that order and never the other way round.

SCHEME_VERSIONconst
1

Bumping this is how a future object layout ships. It is in the preimage, so a v2 scheme is a version bump rather than an argument — and a v1 renderer meeting a v2 object says so out loud instead of rendering nothing.

SITE_DEFINED_KIND_MINconst
128

Kind ids at or above this are reserved for the site and never interpreted by websitekit.

Slot identity

keys, not ordinals (§2).

assertValidSlotKeyfunction
(key: string) => void

Validates a slot key without hashing it. Exposed because a config loader wants to report every bad key at once rather than throwing on the first.

InvalidSlotKeyErrorclass
typeof InvalidSlotKeyError
MAX_KEY_LENGTHconst
128

Long enough for any real path, short enough that a key is never a payload.

slotKeyfunction
(key: string) => Hex

`keccak256(utf8(key))` — the `bytes32` the contract stores, and `uint256(…)` of it is the ERC-721 token id.

slotKeysfunction
(keys: readonly string[]) => Hex[]

Hashes many keys and reports ALL failures together.

slotTokenIdfunction
(key: string) => bigint

The ERC-721 token id for a slot, for wallet and marketplace links.

Reads

one call per page, through `SlotReader` (§5, §11.4).

BuyContextinterface
interface BuyContext { slot: SlotState; expectedTerms: Hex; /** The chain's clock at `blockNumber` — NOT `Date.now()`. */ now: bigint; blockNumber: bigint; }

Everything a buy needs, read at one pinned block.

economicsFromTermsfunction
(terms: SiteTerms) => SiteEconomics

The subset of a site's terms the pricing twin needs, mapped without hand-copying five bps fields.

isTokenSettledfunction
(terms: Pick<SiteTerms, "settlementToken">) => boolean

Whether a site settles in an ERC-20 rather than the chain's native currency.

Listinginterface
interface Listing { ratePerDay: bigint; maxDurationSecs: bigint; /** * The site's cut, SNAPSHOTTED when the listing was written. **Price an existing listing against * this, never against the site's current `siteRentBps`** — the snapshot is …

A position's rental listing. `ratePerDay === 0n` means not listed.

readAccruedRentfunction
(client: PublicClient, site: Address, key: string) => Promise<bigint>

Rent the owner has earned so far, gross of what has already been claimed.

readBuyContextfunction
(client: PublicClient, ref: SiteRef, key: string) => Promise<BuyContext>
readCanEditfunction
(client: PublicClient, site: Address, key: string, account: Address) => Promise<boolean>

Whether an address may write this slot's content.

readEncumbrancefunction
(client: PublicClient, site: Address, key: string) => Promise<Hex>

The `expectedTerms` argument every buy needs (§4).

readListingfunction
(client: PublicClient, site: Address, key: string) => Promise<Listing>
readPendingWithdrawalfunction
(client: PublicClient, site: Address, account: Address) => Promise<bigint>

What a caller can withdraw from this site's pull ledger.

readRentalfunction
(client: PublicClient, site: Address, key: string, nowSecs?: bigint) => Promise<Rental>
readSiteTermsfunction
(client: PublicClient, ref: SiteRef, blockNumber?: bigint) => Promise<SiteTerms>
readSlotfunction
(client: PublicClient, ref: SiteRef, key: string) => Promise<SlotState>

Single-slot convenience. Prefer `readSlots` for anything rendering more than one.

readSlotsfunction
(client: PublicClient, ref: SiteRef, keys: readonly string[], blockNumber?: bigint) => Promise<SlotState[]>

Reads every slot on a page in one call.

readSlotsMultifunction
(client: PublicClient, reader: Address, boards: ReadonlyArray<{ site: Address; keys: readonly string[]; }>, blockNumber?: bigint) => Promise<SlotState[][]>

The directory read: many sites, one round trip.

readUnaccruedRentfunction
(client: PublicClient, site: Address, key: string) => Promise<bigint>

Escrowed rent not yet earned — what a buyer of this position would inherit (§2.4.2).

Rentalinterface
interface Rental { tenant: Address | null; start: bigint; expiry: bigint; /** Net of the fee split — what actually streams to the owner over the term. */ prepaid: bigint; /** How much of `prepaid` has already been swept into the pull ledger…

A tenancy, straight from the site. `readSlots` already carries the fields a page needs; this is for a rental panel that has to show the whole term.

RENTALS_LIB_ABIconst
Abi

`RentalsLib`'s ABI. Needed on its own only rarely; what most callers want is `SITE_EVENTS_ABI`.

SITE_EVENTS_ABIconst
Abi

**The ABI to watch a site's logs with.**

SiteRefinterface
interface SiteRef { site: Address; reader: Address; }

Where to read a site from.

SiteTermsinterface
interface SiteTerms { implementationVersion: bigint; takeBps: bigint; payoutBps: bigint; /** Per-week reversion. `10_000` is none at all. v1 called this `decayBps`. */ reversionBps: bigint; maxReversionWeeks: bigint; cooldownSecs: bigint; p…

A site's terms: the protocol constants it was cloned under, the economics, and the rental and floor policy.

SLOT_READER_ABIconst
Abi

The convenience-view periphery. Redeployable — see the module note.

SLOT_SITE_ABIconst
Abi

The committed `SlotSite` ABI, typed for viem. Kept in sync by `pnpm sync:abi`.

SlotStateinterface
interface SlotState { /** The dotted key from the site's config, e.g. `hero.headline`. */ key: string; /** `keccak256(utf8(key))` — what the contract stores. */ keyHash: Hex; /** `null` when unclaimed, rather than the zero address. */ owner…

One row of the reader's `readSlots`, with the string key the caller asked about carried back.

Writes

request objects for viem, never a wallet of our own.

approvalForfunction
(buy: ReturnType<typeof buildBuy>, settlementToken: Address) => CallRequest<"approve", [Address, bigint]> | null

The approval a built purchase needs before it is sent, or `null` on a native site.

buildApproveSettlementfunction
(settlementToken: Address, site: Address, amount: bigint) => CallRequest<"approve", [Address, bigint]>

Approves the site to pull settlement funds. Only needed on a token site — check with `isNativeSettlement` first, and skip the whole step when it returns true.

buildBuyfunction
(options: BuildBuyOptions) => CallRequest<"buy", [Hex, bigint, Hex, bigint]> | CallRequest<"buyFor", [Address, Hex, bigint, Hex, bigint]>

Builds a `buy` or a `buyFor` depending on whether `recipient` is given.

buildBuyFromfunction
(site: Address, context: { slot: { key: string; charged: bigint; }; expectedTerms: Hex; now: bigint; }, settlementToken: Address, options?: Pick<BuildBuyOptions, "maxPrice" | "slippageBps" | "deadline" | "deadlineSecs" | "recipient">) => Ca…

The path to reach for. Takes a `BuyContext` — quote, encumbrance and chain clock all read at one pinned block — so the ways a buy can be built wrong are unavailable by construction: no torn read between the quote and the terms, no wall-clock deadline, no forgotten `expectedTerms`.

BuildBuyOptionsinterface
interface BuildBuyOptions { site: Address; key: string; /** * What the caller was quoted — `SlotState.charged`. Used to derive `maxPrice` and `value` when * neither is given explicitly. * * **Not `netCost`.** The contract charges the gross …
buildClaimRentfunction
(site: Address, key: string) => CallRequest<"claimRent", [Hex]>

Sweeps earned rent into the owner's pull ledger. Permissionless, and always credits the CURRENT owner rather than the caller — so a keeper can run it for a whole directory without the SDK needing to care who signs.

buildCreateSitefunction
(options: BuildCreateSiteOptions) => CallRequest<"createSite", [SiteConfigTuple, Hex[], bigint[]]> | CallRequest<"createSiteFor", [Address, SiteConfigTuple, Hex[], bigint[]]>

Builds `createSite` or `createSiteFor`.

BuildCreateSiteOptionsinterface
interface BuildCreateSiteOptions { factory: Address; name: string; symbol: string; baseTokenURI: string; treasury: Address; /** * `0x0` for native, or the ERC-20 to settle in. **Frozen at deploy with no setter, ever** — * changing it would …
buildDelistfunction
(site: Address, key: string) => CallRequest<"listForRent", [Hex, bigint, bigint]>

Withdraws a listing. Also the owner's escape valve from an incumbent tenant: `extendRental` needs a live listing, so delisting means the arrangement ends cleanly at the current term's boundary rather than rolling on at a rate the owner has come to regret.

buildEditfunction
(site: Address, key: string, contentHash: Hex) => CallRequest<"edit", [Hex, Hex]>

Writes a slot's content hash. The bytes have to be stored somewhere retrievable by hash BEFORE this lands — §3's first honest caveat is that reads are backend-free but writes are not. A hash on-chain whose bytes were never uploaded is a permanently blank slot that looks exactly like a bug in the SDK.

buildEndRentalfunction
(site: Address, key: string) => CallRequest<"endRental", [Hex]>

Clears a lapsed tenancy and restores the owner's content hash. Permissionless once the term has expired.

buildExtendRentalfunction
(options: BuildRentOptions) => CallRequest<"extendRental", [Hex, bigint, bigint]>

Extends a live tenancy. Current tenant only, and the term must not have lapsed.

buildListForRentfunction
(site: Address, key: string, ratePerDay: bigint, maxDurationSecs: bigint) => CallRequest<"listForRent", [Hex, bigint, bigint]>

Lists a position for rent. Owner only.

buildRegisterSlotsfunction
(site: Address, slots: Readonly<Record<string, bigint>>) => CallRequest<"registerSlots", [Hex[], bigint[]]>

Registers slots. Site-owner only, and slots are closed by default — §7.5, without which anyone who reads the site's repo buys `hero.headline` at floor before launch.

buildRentfunction
(options: BuildRentOptions) => CallRequest<"rent", [Hex, bigint, bigint]>

Opens a tenancy. Anyone may rent; the position must be owned (there is nobody to pay otherwise) and must not already carry a tenancy — including a lapsed one that has not been cleared, which is what makes `buildEndRental` load-bearing rather than housekeeping.

BuildRentOptionsinterface
interface BuildRentOptions { site: Address; key: string; /** Seconds. At least one hour, at most the listing's `maxDurationSecs`. */ durationSecs: bigint; /** * The rate the tenant was shown, from `readListing().ratePerDay`. * * Required an…
buildSetAskfunction
(site: Address, key: string, askFloor: bigint) => CallRequest<"setAsk", [Hex, bigint]>

Posts the owner's **reversion base**: the price the slot reverts *from* over time.

buildSetAvailabilityfunction
(site: Address, keys: readonly string[], available: boolean) => CallRequest<"setAvailability", [Hex[], boolean]>

The publisher's listing toggle (§10.4): a registered slot with availability off cannot be CLAIMED, and nothing else changes — takes and rentals on owned positions are deliberately untouched, because "unpublish" ends where somebody paid. Registration is permanent; this is the reversible half, and it is a batch call because a dashboard toggles boards, not keys.

buildSetBaseTokenURIfunction
(site: Address, uri: string) => CallRequest<"setBaseTokenURI", [string]>

Repoints the ERC-721 metadata base. Owner only, no redeploy.

buildSetEconomicsfunction
(site: Address, economics: SiteEconomicsConfig) => CallRequest<"setEconomics", [bigint, bigint, bigint, bigint, bigint]>

Changes the take economics. Owner only, and **one-directional once the first position is claimed** (§6.1): `takeBps` may only fall, `payoutBps` may only rise, reversion may only get slower, its horizon shorter, and the cooldown shorter. Before that first claim anything goes.

buildSetEditorfunction
(site: Address, key: string, editor: Address) => CallRequest<"setEditor", [Hex, Address]>

Grants or revokes delegated editing. Pass the zero address to revoke.

buildSetEditorWithSigfunction
(site: Address, key: string, editor: Address, deadline: bigint, signature: Hex) => CallRequest<"setEditorWithSig", [Hex, Address, bigint, Hex]>

Relays a grant the owner signed. The submitter pays the gas and gains nothing — the grant records the OWNER as grantor, so a relayer cannot make itself the editor by relaying.

buildSetFloorfunction
(site: Address, key: string, floor: bigint) => CallRequest<"setFloor", [Hex, bigint]>

Moves a slot's floor, within the site's `floorDeltaBps` band and `floorChangeCooldown`.

buildSetFloorPolicyfunction
(site: Address, policy: { floorDeltaBps: bigint; floorChangeCooldown: bigint; maxAskBps: bigint; }) => CallRequest<"setFloorPolicy", [bigint, bigint, bigint]>

Tightens the floor lever and the ask cap. After the lock these may only tighten, never loosen.

buildSetRentalTermsfunction
(site: Address, terms: { siteRentBps: bigint; maxRentalTerm: bigint; minRentBps: bigint; }) => CallRequest<"setRentalTerms", [bigint, bigint, bigint]>

Changes the rental terms. Owner only, and **freely mutable in both directions even after the lock** — because rent binds nobody involuntarily. An owner who dislikes a new rate simply does not list, and a live tenancy is unaffected: the fee was taken at `rent` time and the site's cut is snapshotted per listing. That recourse is exactly what take economics lack (§2.5.1).

buildSweepTreasuryfunction
(site: Address) => CallRequest<"sweepTreasury", []>

Sweeps the whole treasury to the site's `treasury` address. Permissionless, and pays `treasury` rather than the caller — so it grants no authority, on identical reasoning to `withdrawFor`.

buildWithdrawForfunction
(site: Address, account: Address) => CallRequest<"withdrawFor", [Address]>

Claims a pending balance. Permissionless and pays the account that is owed, never the caller.

buildWithdrawTreasuryfunction
(site: Address, amount: bigint) => CallRequest<"withdrawTreasury", [bigint]>

Moves part of the site's treasury. Owner only.

CallRequestinterface
interface CallRequest<TName extends string, TArgs extends readonly unknown[]> { address: Address; abi: Abi; functionName: TName; args: TArgs; value?: bigint; }

What viem's `writeContract` / `simulateContract` take.

DEFAULT_DEADLINE_SECSconst
300n

How long a buy stays valid after it is built. Short, because the whole point of a deadline is that a transaction stuck in the mempool through a price move should expire rather than land at a price nobody agreed to.

DEFAULT_SLIPPAGE_BPSconst
100n

Slippage headroom applied to the quoted price when the caller does not supply an explicit `maxPrice`. Zero would be correct and unusable: the quote is read a block or two before the transaction lands, and any reversion boundary crossed in between changes the number.

editorGrantTypedDatafunction
(options: { site: Address; chainId: number; siteName: string; key: string; editor: Address; nonce: bigint; deadline: bigint; }) => { domain: { name: string; version: string; chainId: number; verifyingContract: `0x${string}`; }; types: { Edi…

The EIP-712 payload an owner signs to delegate editing without transacting.

ERC20_ABIconst
readonly [{ readonly type: "function"; readonly name: "approve"; readonly stateMutability: "nonpayable"; readonly inputs: readonly [{ readonly name: "spender"; readonly type: "address"; }, { readonly name: "amount"; readonly type: "uint256"…

The two entries of ERC-20 the token settlement path actually needs.

InvalidEconomicsErrorclass
typeof InvalidEconomicsError
isNativeSettlementfunction
(settlementToken: Address) => boolean

`0x0` is native settlement; anything else is an ERC-20 whose `msg.value` must be exactly zero.

SiteEconomicsConfiginterface
interface SiteEconomicsConfig { /** 1.4x is `14_000`. Must exceed `payoutBps + protocolBps`, and is capped at `30_000`. */ takeBps: bigint; /** 1.15x is `11_500`. Must be at least `10_000` — a site can only monetize the spread. */ payoutBps…

The take economics a site starts with. Mutable before the first claim and a one-way ratchet after it (§6.1) — so this is a starting point rather than a permanent choice, which is a real change from v1 where every field here was frozen at `initialize()` forever.

SiteFloorPolicyConfiginterface
interface SiteFloorPolicyConfig { /** How far one `setFloor` may move a floor. `1..2_000`. */ floorDeltaBps: bigint; /** Seconds between floor changes. At least 24 hours. */ floorChangeCooldown: bigint; /** Ceiling on an owner's ask, in bps…

The floor lever and the ask cap. May only tighten after the first claim.

SiteRentalConfiginterface
interface SiteRentalConfig { /** The site's cut of rent. `siteRentBps + protocolRentBps` must land in `[1_000, 4_000]`. */ siteRentBps: bigint; /** The longest term the site will allow, in seconds. One hour to 365 days. */ maxRentalTerm: bi…

The rental policy. Freely mutable for the site's whole life (§2.5.1).

SLOT_FACTORY_ABIconst
Abi

Render escrow

one vault per board, outside `SlotSite`; the pin is all it needs from bytecode.

ATTESTOR_ABIconst
Abi
buildApproveVaultfunction
(site: Address, vault: Address) => CallRequest<"setApprovalForAll", [Address, boolean]>

The surrender's consent: `setApprovalForAll(vault, true)` on the SITE, so `claim` can move the holder's token into the vault. Sent by the holder, on the site, before `buildClaim`.

buildBookfunction
(vault: Address) => CallRequest<"book", []>

Sweeps the site and books the unbooked inbound. Permissionless — always to the board's owner.

buildClaimfunction
(vault: Address, key: string, minPaid: bigint) => CallRequest<"claim", [Hex, bigint]>

The holder surrenders `key` for up to what they paid. **The holder's call**, or an operator they approved — and the vault itself must be approved to move the token first, which is `buildApproveVault`. A claim without that approval fails at the surrender and credits nothing.

buildClearDarkfunction
(vault: Address) => CallRequest<"clearDark", []>

The attestor's. Closes the episode and adds it to `darkAccrued`.

buildCreateEscrowedSitefunction
(options: BuildCreateEscrowedSiteOptions) => CallRequest<"createEscrowedSite", [Address, unknown, Hex[], bigint[]]>

Builds `EscrowFactory.createEscrowedSite`.

BuildCreateEscrowedSiteOptionsinterface
interface BuildCreateEscrowedSiteOptions extends Omit<BuildCreateSiteOptions, 'factory' | 'owner' | 'treasury' | 'pinTreasury'> { /** The `EscrowFactory`, not the `SlotFactory`. */ escrowFactory: Address; /** * Who owns the board. **Require…
buildFundReservefunction
(vault: Address, amount: bigint, settlementToken: Address) => CallRequest<"fundReserve", [bigint]>

Adds reserve only a claim may spend — what lets a claim pay `lastPrice` in full rather than the publisher's 95% of it. Native sends `value`; a token board pulls `amount` and needs an allowance on the VAULT (`buildApproveSettlement` with the vault as spender).

buildMarkDarkfunction
(vault: Address) => CallRequest<"markDark", []>

The attestor's. Stops every immature deposit's clock.

buildReleasefunction
(vault: Address, id: bigint) => CallRequest<"release", [bigint]>

Credits a mature deposit to whoever owned the board when it was booked. Permissionless.

buildSweepForeignfunction
(vault: Address, token: Address) => CallRequest<"sweepForeign", [Address]>

Pays the board's owner any balance that is not the settlement token. `0x0` is native — on a token board that is the common royalty case, not the residue.

buildVaultWithdrawForfunction
(vault: Address, account: Address) => CallRequest<"withdrawFor", [Address]>

Pays `account` what the vault has credited it. Permissionless; only `account` is paid.

buildWithdrawReservefunction
(vault: Address, amount: bigint, to: Address) => CallRequest<"withdrawReserve", [bigint, Address]>

The factory owner's. Refused while the board is dark.

ESCROW_FACTORY_ABIconst
Abi
ESCROW_VAULT_ABIconst
Abi
EscrowBindinterface
interface EscrowBind { /** `site.treasury() == vault` — the publisher's cut has nowhere else to go. */ routesHere: boolean; /** `site.treasuryPinned()` — and nobody can repoint it. */ pinned: boolean; /** `vault.site() == site` — and the va…
EscrowParamsinterface
interface EscrowParams { /** Seconds a deposit must be served in the light before it is the publisher's. */ windowSecs: bigint; /** Seconds after `markDark` before any holder may claim — the window in which `clearDark` * corrects a mistake …

The factory's policy, copied onto each vault at bind and immutable for that board thereafter.

readAttestorfunction
(client: PublicClient, registry: Address) => Promise<Address | null>

The key the registry currently names, or `null` when it names nobody (fail-open).

readClaimablefunction
(client: PublicClient, vault: Address, key: string) => Promise<bigint>

What `claim(key)` would credit right now, or `0n` when it would revert for any reason.

readDepositsfunction
(client: PublicClient, vault: Address) => Promise<VaultDeposit[]>

Every deposit on a vault, with the vault's own maturity verdict beside each.

readEscrowBindfunction
(client: PublicClient, site: Address, vault: Address) => Promise<EscrowBind>

The guarantee, checked in BOTH directions.

readEscrowPolicyfunction
(client: PublicClient, escrowFactory: Address) => Promise<EscrowParams>

The factory's current policy — what the NEXT board will be bound with. A vault already bound carries its own copy (`readVault`), and the two can honestly differ.

readVaultfunction
(client: PublicClient, vault: Address) => Promise<VaultState>
readVaultOffunction
(client: PublicClient, escrowFactory: Address, site: Address) => Promise<Address | null>

The vault the escrow factory bound to `site`, or `null` if it created none.

readVaultPendingfunction
(client: PublicClient, vault: Address, account: Address) => Promise<bigint>

What `account` may withdraw from the vault's pull ledger.

VaultDepositinterface
interface VaultDeposit { id: bigint; /** Remaining, undrained. Zero once released or fully claimed. */ amount: bigint; bookedAt: bigint; darkAtBooking: bigint; /** Who owned the board when this was booked, and who `release` pays. */ benefic…
VaultStateinterface
interface VaultState { site: Address; settlementToken: Address; windowSecs: bigint; claimDelaySecs: bigint; minTransitionSecs: bigint; minBooking: bigint; /** `0n` when live. While non-zero, maturity is evaluated as of this moment. */ darkS…

Site config

the file a builder edits (§0).

Chaininterface
interface Chain { id: number; /** * What a person is told they are on. Shown by `testnetNotice` and by the deposit screen, which is * why it is a NAME and never the id — `lib/auth.ts` → `NEVER_SHOW` withholds a chain id as a * value, and a …

The chains this SDK knows how to name, which is a different list from the ones it has addresses for.

chainForfunction
(id: number) => Chain

The chain with this id, or a refusal naming the ones there are.

CHAINSconst
Record<number, Chain>
CONTENT_KIND_BY_NAMEconst
Record<SlotKindName, number>
DEFAULT_CONTENT_GATEWAYfunction
(cid: string) => string
DEFAULT_SETTLEMENT_DECIMALSconst
18

Decimals a floor string is parsed against when the config does not say otherwise.

defineSitefunction
(input: DefineSiteInput) => SiteConfig

Validates a site config and normalizes it into the shape every consumer wants.

DefineSiteInputinterface
interface DefineSiteInput { /** The clone's address, returned by `createSite()`. */ address: Address; /** * The `SlotReader` every read goes through (§11.4). * * Required rather than resolved from a chain table, because the reader is delibe…
InvalidSiteConfigErrorclass
typeof InvalidSiteConfigError
NATIVE_CURRENCYconst
SettlementCurrency

Native settlement on every chain this SDK names.

parseFloorfunction
(amount: string, decimals?: number) => bigint

Parses a human decimal amount against a settlement token's decimals.

readSettlementCurrencyfunction
(client: PublicClient, settlementToken: Address, blockNumber?: bigint) => Promise<SettlementCurrency>

The currency of a board, read from its settlement token — `readSiteTerms().settlementToken`.

ROBINHOOD_MAINNET_CHAINconst
Chain

Robinhood Chain mainnet. The v2 protocol is deployed here (2026-09-21) and so is render escrow (2026-09-22) — see `ROBINHOOD_MAINNET` and `ROBINHOOD_MAINNET_ESCROW` in `addresses.ts`.

ROBINHOOD_MAINNET_USDGconst
SettlementToken

The real USDG — `Global Dollar`, issued by Paxos, 6 decimals. Confirmed 2026-09-19 against Robinhood's own contract documentation and Paxos's, not merely read off the chain.

ROBINHOOD_TESTNET_CHAINconst
Chain

Robinhood Chain testnet — free money, a mintable stand-in dollar, and every seeded example board.

ROBINHOOD_TESTNET_TUSDconst
SettlementToken

`TestUSD` — a permissionlessly mintable stand-in, verified on Blockscout. It exists because the testnet's own USDG is role-gated and nobody outside its issuer can obtain any. Six decimals, so a floor written for mainnet means the same number of dollars here.

SETTLEMENT_TOKENSconst
Record<number, SettlementToken>
SettlementCurrencyinterface
interface SettlementCurrency { symbol: string; decimals: number; }

What a board's prices are counted in, for showing a person a number.

SettlementTokeninterface
interface SettlementToken { address: Address; decimals: number; symbol: string; /** Whether anybody may mint it. True only for a test stand-in; never for real money. */ mintable: boolean; }
settlementTokenForfunction
(chainId: number) => SettlementToken

The token a new board on this chain should settle in, or a refusal naming the chains there are. Throws rather than falling back to native: a default is silently right on one kind of site and wrong by 1e12 on the other.

SiteConfiginterface
interface SiteConfig { address: Address; reader: Address; /** `{ site, reader }`, ready to hand to any read. */ ref: SiteRef; chain: Chain; /** What the floors above were parsed against. Carried so a consumer can format them back. */ decima…
SlotDefinitioninterface
interface SlotDefinition { key: string; kind: SlotKindName; contentKind: number; floor: bigint; }
SlotDefinitionInputinterface
interface SlotDefinitionInput { kind: SlotKindName; /** * A decimal string in the site's SETTLEMENT currency — `'0.002'`, not `2000000000000000n`. * * A string because this is the one number a builder types by hand, and `0.002` in a config …
slotFloorsfunction
(config: SiteConfig) => Record<string, bigint>

The `{ key: floor }` map `buildCreateSite`/`buildRegisterSlots` take.

SlotKindNametype
type SlotKindName = 'text' | 'link' | 'image' | 'video';

How `@websitekit/react` should render a slot. Purely a CLIENT-side convention — the chain stores an opaque hash and knows nothing about kinds, and a site rendering its own payload structure through `useSlot()` can ignore this entirely.

Deployed addresses

mainnet and its testnet, through `deploymentFor` (§7.9).

DEMO_SITEconst
`0x${string}`

The TESTNET demo board — native ETH, the scaffold's default before mainnet (§6). **v2, seeded 2026-08-19 by `scripts/seed-demo.ts`.**

DEMO_SITE_MAINNETconst
`0x${string}`

The mainnet demo board — Northwind, settling in USDG. **Seeded 2026-10-03 by `scripts/seed-demo.ts` and given content by `scripts/seed-content.ts`**, against `ROBINHOOD_MAINNET`.

DEMO_SITE_V1const
`0x${string}`

The v1 demo board. Unreachable from this package — kept so the record is not silently dropped.

DEMO_SITESconst
Record<number, `0x${string}`>

The scaffold's demo board on each chain, keyed by chain id.

demoSiteForfunction
(chainId: number) => Address | undefined
Deploymentinterface
interface Deployment { chainId: number; /** Which contract generation this deployment is. v2 adds rentals, the ask and token settlement. */ version: 1 | 2; /** The audited `SlotSite` every site on this chain is a clone of. */ implementation…
deploymentForfunction
(chainId: number) => Deployment
DEPLOYMENTSconst
Record<number, Deployment>
ESCROW_DEPLOYMENTSconst
Record<number, { chainId: number; factory: Address; attestor: Address; vault: Address; }>

Render escrow, by chain — the escrow counterpart to `DEPLOYMENTS`.

escrowDeploymentForfunction
(chainId: number) => { chainId: number; factory: Address; attestor: Address; vault: Address; }
EXAMPLE_SITESconst
{ readonly dispatch: "0xE0d1cF918a53eB92Ec672fa93530601ef4758Aa7"; readonly devconf: "0xB1A7262F3eD2e54F4d950c5Ae76A24D726156932"; readonly remoteroles: "0xa7aea56116E6d478B501E2d75828A286e9E7C489"; readonly vaultline: "0x67E2A12B023c7715Ae…

Example boards, deployed to answer "would this work for my site?" — which the demo board cannot, because its shape is inherited and it is the only shape the docs show. **v2, seeded 2026-08-19.**

EXAMPLE_SITES_BY_CHAINconst
Record<number, Record<string, `0x${string}`>>

Each chain's example boards, keyed by chain id. Like `demoSiteFor`, `exampleSitesFor` answers `undefined` for a chain with none rather than another chain's boards.

EXAMPLE_SITES_MAINNETconst
{ readonly dispatch: "0x6Db93fE0dd003f616081D0e8bDA58da33B464Eef"; readonly devconf: "0x951B16F06D31707FdE54fe177918C55550BaAaa0"; readonly remoteroles: "0xc1920ee84B1da603A514f5a5403019b7d1b98627"; readonly vaultline: "0x50838AfEc1329dF3fA…

The four example boards on MAINNET, settling in USDG. **Seeded 2026-10-03 by `scripts/seed-examples.ts`, content by `scripts/seed-example-content.ts`**, against `ROBINHOOD_MAINNET`. Same layouts and economics as `EXAMPLE_SITES`, in their final shape from the start: every content slot owned across two demo accounts, a couple taken once, and only the edge slots open. Floors $2 for each board's most prominent slot, $1 for the rest.

EXAMPLE_SITES_V1const
{ readonly dispatch: "0x895Fb4Ba710b0f495983A582b5c9013ccC33736c"; readonly devconf: "0xA7f8Dba26F82cc1deD9a63F28932eC87128834F0"; readonly remoteroles: "0x8c0d776ece615Ba01bE5038b95aA9Df5F3411f99"; readonly vaultline: "0xE41addf32313915F98…

The v1 example boards. Unreachable from this package — their implementation source is deleted and the SDK no longer carries their ABI. Kept as provenance, and because they still exist on chain.

exampleSitesForfunction
(chainId: number) => Record<string, Address> | undefined
ROBINHOOD_MAINNETconst
Deployment

**Mainnet.** Deployed 2026-09-19 by `scripts/deploy-protocol.ts` against chain 4663, the first websitekit deployment on a chain where the money is real.

ROBINHOOD_MAINNET_ESCROWconst
{ readonly chainId: number; readonly factory: "0x6325e655f01c1c2f5d7f05de230a31a9ddc82513"; readonly attestor: "0xed0d571da2393cc6701a0d0d3b0fa090aad6987c"; readonly vault: "0x6891bae1bdcb0ef417aaf38a147619139df69b8f"; }

Render escrow on MAINNET, deployed 2026-09-22 by `scripts/deploy-escrow.ts` against `ROBINHOOD_MAINNET` above. `docs/mainnet_deployment.md` step 1; `docs/escrow_mainnet.md` E-7 steps 2 to 4.

ROBINHOOD_TESTNETconst
Deployment

**The live deployment** — the treasury-pin generation, deployed 2026-09-03. Unaudited, testnet only. Its implementation is the first carrying `SiteConfig.pinTreasury`, which is the whole of what render escrow needs from frozen bytecode (`docs/PROTOCOL-SPEC.md` §10.4.1).

ROBINHOOD_TESTNET_ESCROWconst
{ readonly chainId: number; readonly factory: "0xbe82523ae5d552daf772c4075a38c9b9c202eb86"; readonly attestor: "0x0fcde0325301bc8328b48ce8e17c7041b19371f2"; readonly vault: "0x8a09723821523023683ab1dd501147f37e53d8ab"; }

Render escrow, **redeployed 2026-09-21** by `scripts/deploy-escrow.ts` against the generation above, to put `claim`'s minimum-out on a chain before mainnet saw it first. The generation it replaced is `ROBINHOOD_TESTNET_ESCROW_R1` below.

ROBINHOOD_TESTNET_ESCROW_R1const
{ readonly chainId: number; readonly factory: "0x9be87b6732a46cecfca4e46fbe65a6c46aedfddf"; readonly attestor: "0x4ce6109f7b5bf12046299fb4fee49f963b0f06ef"; readonly vault: "0x38aed6b3eef84aa178d1c8606c824594f61f0006"; }

The escrow generation this superseded, deployed 2026-09-03 and replaced 2026-09-21.

ROBINHOOD_TESTNET_R2const
Deployment

The availability revision, deployed 2026-08-19 and **superseded 2026-09-03** by the pin generation above. Still live, still readable by this SDK, and still where every board in `DEMO_SITE`, `EXAMPLE_SITES` and `SMOKE_TEST_SITE` is a clone — so this is not provenance the way `_R1` and `_V1` are. It is the generation the seeded boards are ON.

SMOKE_TEST_SITEconst
`0x${string}`

The first site created through the v2 factory, by `scripts/smoke-deployment.ts`.

@websitekit/sdk/image-boards

The image-board client, under its own entry point because its names (quote, readBlock, Rect) are generic. Groups are the banner comments in image-boards.ts, then each file it re-exports.

Deployments

IMAGE_BOARD_DEPLOYMENTSconst
Readonly<Record<number, ImageBoardDeployment>>

Image boards, by chain. The earlier generation's addresses (testnet `0x2032…8f41`, mainnet `0x8af0…f275`, both empty of boards) answer a different ABI, so they are not listed; the mainnet one allows no token.

ImageBoardDeploymentinterface
interface ImageBoardDeployment { chainId: number; /** Every board is an EIP-1167 clone of this. */ implementation: Address; /** What every board of `implementation` delegatecalls for its set-up and rentals. */ extension: Address; /** What b…
imageBoardDeploymentForfunction
(chainId: number) => ImageBoardDeployment

The deployment on this chain. **Throws** rather than answering undefined, naming the chains that have one: no deployment, no boards — and never another chain's addresses.

ROBINHOOD_MAINNET_IMAGE_BOARDSconst
ImageBoardDeployment

Robinhood Chain, deployed 2026-10-22 by `scripts/deploy-image-boards.ts`: the token generation, as on testnet, settling in real USDG (`ROBINHOOD_MAINNET_USDG`). The collection is owned by the protocol's deployer. All four verified on Sourcify (creation and runtime an exact match) and on Etherscan.

ROBINHOOD_TESTNET_IMAGE_BOARDSconst
ImageBoardDeployment

Robinhood Chain testnet, deployed 2026-10-21 by `scripts/deploy-image-boards.ts`: the token generation (spec §13) — the Boards collection "PageMarkets Images" (`PMIMG`), every board an ERC-721 of its blocks, metadata built on chain by the renderer (thumbnails at `https://pagemarkets.com/i/boards/`, the live view the pinned reference renderer page). The collection is owned by the testnet deployer; the token is a mintable TestUSD with EIP-2612 permit. All four verified on Sourcify, creation and runtime an exact match.

The protocol's terms, as the contracts carry them

IMAGE_BLOCK_MAX_RENTAL_SECSconst
31536000n
IMAGE_BLOCK_MIN_RENTAL_SECSconst
3600n

The shortest and longest term a block can be rented for: `MIN_RENTAL_DURATION`, `MAX_RENTAL_TERM`.

IMAGE_BLOCK_RENT_ROYALTY_BPSconst
500n

What a rental pays whoever holds the board's NFT then, beside the protocol's cut: `ImageBoard.RENT_ROYALTY_BPS`.

IMAGE_BLOCK_RESALE_ROYALTY_BPSconst
500n

What a block's resale pays whoever holds the board's NFT then: `ImageBoard.RESALE_ROYALTY_BPS`.

IMAGE_BOARD_PROTOCOL_BPSconst
500n

The protocol's cut of every square sold and every block resold. The deploy script refuses any other.

IMAGE_BOARD_ROYALTY_BPSconst
500n

ERC-2981, paid to a board's creator when the board's NFT is resold: `ImageBoardCollection.ROYALTY_BPS`. A block's own ERC-2981 is `IMAGE_BLOCK_RESALE_ROYALTY_BPS`, to whoever holds the board's NFT then.

IMAGE_BOARD_SELLER_BPSconst
bigint

What whoever holds the board is credited per square sold, in bps of its price.

resaleSplitfunction
(price: bigint, protocolBps?: bigint) => { protocolCut: bigint; royalty: bigint; toOwner: bigint; }

How a resale at `price` is credited — **a twin of the contract's `resaleSplit`**, for showing an owner what they receive. Both shares round down and the owner gets the remainder, so the three sum to the price. The sale itself never reads this.

Reads

BlockRentalinterface
interface BlockRental { tenant: Address; start: bigint; expiry: bigint; prepaid: bigint; claimed: bigint; tenantHash: Hex; /** Set once `poke` has announced this term's end; cleared when a new term starts. */ poked: boolean; }

A block's tenancy (`IMAGE-BOARD-SPEC.md` §12). `prepaid` is net of both cuts and streams to the owner.

BlockRentListinginterface
interface BlockRentListing { ratePerDay: bigint; maxDurationSecs: bigint; }
BlockStateinterface
interface BlockState extends Rect { tokenId: bigint; owner: Address; /** Zero until the first write. */ contentHash: Hex; version: number; /** `0x0…0` when nobody is granted; a grant dies on transfer, on chain. */ editor: Address; /** What …
gridStateOffunction
(board: ImageBoardState, blocks: readonly BlockState[], cells?: CellMap) => GridState

The twin's view of a board, from the reads a screen already makes, pinned to one block. `blocks` is every block (`readBlocks`); the cell map is painted from them (`cellMapFromBlocks`) unless given — `readCellMap` reads it instead.

ImageBoardStateinterface
interface ImageBoardState { address: Address; /** The board's NFT: `collection`'s token `boardToken`. */ collection: Address; boardToken: bigint; /** Whoever holds the board's NFT now — who the next square sold pays. Not frozen. */ seller: …
isNoSuchBlockfunction
(error: unknown) => boolean

Whether `error` is the board's `NoSuchBlock` revert, however deep viem wrapped it. Walked by `cause` and `name`, never `instanceof`: a caller's viem is often another copy than this package's (the platform's is), and a class from one copy is not an instance of the other's.

ReadAtinterface
interface ReadAt { at?: bigint; }

`at` pins every read to one block. Without it each read answers at whatever block the RPC is on, and a batching client splits a large batch across several `eth_call`s, so one board's blocks could be read either side of a buy. viem batches calls that share a block number together, so pinning costs no extra round trips.

readBlockfunction
(client: PublicClient, board: Address, tokenId: bigint, opts?: ReadAt) => Promise<BlockState>

One SOLD block, its holder and its content: `ownerOf` reverts for a number never sold (ERC-721), so this does too. `readBlocks` asks only 1..blockCount.

readBlockApprovedfunction
(client: PublicClient, board: Address, tokenId: bigint) => Promise<Address>

Who may move this one block besides its owner; zero for nobody. Ends with every change of owner.

readBlockBalancefunction
(client: PublicClient, board: Address, owner: Address) => Promise<number>

How many of this board's blocks `owner` holds.

readBlockCountfunction
(client: PublicClient, board: Address, opts?: ReadAt) => Promise<number>

How many blocks have been sold — block numbers run 1..this. The one read a listing makes per board.

readBlockFingerprintfunction
(client: PublicClient, board: Address, tokenId: bigint) => Promise<Hex>

ERC-5646: changes with a take, a picture, a term or a listing — an order that names it cannot fill after.

readBlockRectfunction
(client: PublicClient, board: Address, tokenId: bigint) => Promise<Rect>

Where a block is, alone: one read, for a caller that needs nothing else about it. A block never moves.

readBlocksfunction
(client: PublicClient, board: Address, blockCount: number, opts?: ReadAt) => Promise<BlockState[]>

Every block, its holder and its content, in one batch — `blockCount` from `readImageBoard`.

readBlockTokenURIfunction
(client: PublicClient, board: Address, tokenId: bigint) => Promise<string>

A block's ERC-721 metadata, built on chain: `data:application/json;base64,…`. Reverts for one never sold.

readBoardContractURIfunction
(client: PublicClient, board: Address) => Promise<string>

ERC-7572: the board's own collection — its name and the original picture.

readBoardURIfunction
(client: PublicClient, board: Address) => Promise<string>

The board token's metadata (what the Boards collection's `tokenURI` returns for it).

readBuyErrorfunction
(client: PublicClient, board: Address, rects: readonly Rect[]) => Promise<BlockErrorName>

The BUY GATE: what `buyBlocks` would revert with for these rectangles, now — the contract's own `buyError`, in its order. A buy action asks this immediately before anyone signs, so the screen's preview (`buyError` in `image-grid.ts`) is never what decides.

readCanEditfunction
(client: PublicClient, board: Address, tokenId: bigint, account: Address) => Promise<boolean>
readCellMapfunction
(client: PublicClient, board: Address, grid: { cols: number; rows: number; }, opts?: ReadAt) => Promise<CellMap>

Which block holds every cell, in one batch of `cellRow` reads, a row each. `grid` is the board's (`readImageBoard`); it never changes.

readCollectionImplementationfunction
(client: PublicClient, collection: Address) => Promise<Address>

Which implementation the Boards collection clones NEW boards from: its owner can change it (`setImplementation`). A creator asks this before creating, and refuses one it does not expect (decision 11): a board's rules are its implementation's, for good.

readEditorNoncefunction
(client: PublicClient, board: Address, owner: Address) => Promise<bigint>
readFreeCellsfunction
(client: PublicClient, board: Address, opts?: ReadAt) => Promise<number>

Cells no block holds: zero once every square has had a first sale. They can still be taken.

readImageBoardfunction
(client: PublicClient, board: Address, opts?: ReadAt) => Promise<ImageBoardState>

Everything about a board that is not a block, in one batch. All of it is frozen at creation except `blockCount`, `seller`, which follows the board's NFT, and `priceBps`, which falls.

readImageBoardPendingfunction
(client: PublicClient, board: Address, account: Address) => Promise<bigint>

What the board owes `account` (whoever held the board at a sale, or the protocol) on its pull ledger.

readIsBlockOperatorfunction
(client: PublicClient, board: Address, owner: Address, operator: Address) => Promise<boolean>

Whether `operator` may move every block `owner` holds on this board.

readOwnerOffunction
(client: PublicClient, board: Address, tokenId: bigint) => Promise<Address>

Reverts for a block never sold (ERC-721).

readPriceBpsfunction
(client: PublicClient, board: Address, opts?: ReadAt) => Promise<number>

What share of the creation prices a square costs now. The one board read that changes by an act of its holder.

readProtocolBpsfunction
(client: PublicClient, board: Address) => Promise<bigint>

The board implementation's protocol cut, which a resale takes at (`resaleSplit`).

readProtocolTreasuryfunction
(client: PublicClient, board: Address) => Promise<Address>

Who the protocol's cut is credited to: an immutable of the implementation every board shares.

readQuoteBlocksfunction
(client: PublicClient, board: Address, rects: readonly Rect[]) => Promise<bigint>

What the contract charges for these rectangles bought together, now: exactly what `buyBlocks` pulls, and what a buy names as its most (`maxTotal`). Reverts when `readBuyError` is not `none`, so ask that first. `quoteBlocks` in `image-grid.ts` is the screen's preview of it.

readSoldBlockfunction
(client: PublicClient, board: Address, tokenId: bigint, opts?: ReadAt) => Promise<BlockState | null>

`readBlock`, or null for a number never sold — which `ownerOf` refuses with `NoSuchBlock` (ERC-721, spec §13.4), where the earlier generation answered zero. Only that refusal is null: an RPC failure still throws, so a node that is down never reads as "no such block".

readTakePricefunction
(client: PublicClient, board: Address, tokenId: bigint) => Promise<bigint>

What taking every square the block still holds would cost now, in the token's smallest units — the figure its metadata shows, and what a buy pays for that part. A reading: it falls weekly with no transaction. Asked of the board's own renderer.

readZonesfunction
(client: PublicClient, board: Address, opts?: ReadAt) => Promise<Zone[]>

The board's zones, frozen at creation: what a listing needs to say "from" rather than "per square".

sourceCidOffunction
(board: Pick<ImageBoardState, "sourceCid">) => string

The board's source image's IPFS address, as a string (`b…`), from `sourceCid`.

Builders

blockEditorGrantTypedDatafunction
(o: { board: Address; chainId: number; tokenId: bigint; editor: Address; nonce: bigint; deadline: bigint; }) => { domain: { name: string; version: string; chainId: number; verifyingContract: `0x${string}`; }; types: { EditorGrant: { name: s…
BOARD_DOMAIN_NAMEconst
"Image Board"

The grant an owner signs so someone else can relay it. Every board's domain has the same name, which names no product; `verifyingContract` is what tells one board's grants from another's.

buildApproveBlockfunction
(o: { board: Address; spender: Address; tokenId: bigint; }) => CallRequest<"approve", [Address, bigint]>

`approve`: `spender` may move this one block (only move it), until it changes hands. Zero clears it.

buildBuyBlocksfunction
(o: { board: Address; recipient: Address; rects: readonly Rect[]; maxTotal: bigint; deadline: bigint; }) => CallRequest<"buyBlocks", [Address, unknown, bigint, bigint]>

`buyBlocks`, for a payer that has already approved the board: every rectangle its own block, all or nothing. `maxTotal` is the total the buyer was shown (`readQuoteBlocks`); the contract refuses the buy (`PriceTooHigh`) if the cells cost more when it lands, and after `deadline` (seconds).

buildBuyBlocksWithPermitfunction
(o: { board: Address; recipient: Address; rects: readonly Rect[]; maxTotal: bigint; permit: PermitSignature; }) => CallRequest<"buyBlocksWithPermit", [Address, unknown, bigint, bigint, number, Hex, Hex]>

`buyBlocksWithPermit`: one signature (`permitTypedData`) plus one transaction. `maxTotal` is the total the buyer was shown, and the permit is signed for exactly it; its deadline is the buy's. The board pulls what the cells cost when the buy lands and refuses it (`PriceTooHigh`) above `maxTotal` — a take, a later buy or a week's reversion can move it either way.

buildCreateImageBoardfunction
(o: CreateImageBoardOptions) => CallRequest<"createBoardFor", [Address, Hex]>

`ImageBoardCollection.createBoardFor`. Refuses here what the contract would refuse, so a bad config fails before anyone spends gas on a revert that names nothing.

buildEditBlockfunction
(o: { board: Address; tokenId: bigint; contentHash: Hex; }) => CallRequest<"edit", [bigint, Hex]>

`edit`: the owner or the current editor writes the block's content hash.

buildImageBoardWithdrawForfunction
(o: { board: Address; account: Address; }) => CallRequest<"withdrawFor", [Address]>

Pays `account` what the board owes it. Permissionless, and pays only `account`, so anyone may send it.

buildLowerPricesfunction
(o: { board: Address; priceBps: number; }) => CallRequest<"lowerPrices", [bigint]>

`lowerPrices`: every free square to `priceBps` of the price set at creation; sold cells never see it. The board's holder sends it; the contract refuses anyone else, and anything not below the current share.

buildPokeBlockfunction
(o: { board: Address; tokenId: bigint; }) => CallRequest<"poke", [bigint]>

`poke`: anyone announces (ERC-4906) that a term which lapsed with the tenant's picture showing has changed the board back. Once per term, after it ends. A term ends with no transaction, so without this a marketplace keeps the tenant's picture until it refreshes on its own.

buildSetBlockEditorfunction
(o: { board: Address; tokenId: bigint; editor: Address; }) => CallRequest<"setEditor", [bigint, Address]>

`setEditor`, sent by the owner. Zero clears the grant.

buildSetBlockEditorWithSigfunction
(o: { board: Address; tokenId: bigint; editor: Address; deadline: bigint; signature: Hex; }) => CallRequest<"setEditorWithSig", [bigint, Address, bigint, Hex]>

Relays a signed grant. The grant records the OWNER as grantor, so relaying confers nothing.

buildSetBlockOperatorfunction
(o: { board: Address; operator: Address; approved: boolean; }) => CallRequest<"setApprovalForAll", [Address, boolean]>

`setApprovalForAll`: `operator` may move every block the sender holds on this board (a marketplace's ask).

buildTransferBlockfunction
(o: { board: Address; from: Address; to: Address; tokenId: bigint; }) => CallRequest<"transferFrom", [Address, Address, bigint]>

ERC-721 `transferFrom`: moves a block from `from` to `to`, sent by `from`, an address approved for this block, or an operator `from` approved. No receiver check — an address that cannot use a block still holds it; a marketplace moves blocks the same way. Settles the term's streamed rent to `from` and ends their listing, rent offer, editor grant and approval; the tenancy carries on.

CreateImageBoardOptionsinterface
interface CreateImageBoardOptions { collection: Address; /** Who receives the board's NFT, is paid for its squares and gets its royalty. Required: whoever * sends the creation (a relayer, say) must never be it by default. */ seller: Address…
IMAGE_BOARD_CONFIG_PARAMSconst
readonly [{ readonly type: "tuple"; readonly components: readonly [{ readonly name: "settlementToken"; readonly type: "address"; }, { readonly name: "width"; readonly type: "uint32"; }, { readonly name: "height"; readonly type: "uint32"; },…

`ImageBoard.Config`, as `initialize` decodes it. Since 2026-10-20 the collection passes a board's set-up through as bytes it never reads — so a later implementation may take another shape — and the struct is no longer in any ABI. Written out here, and pinned by creating boards with zones, names and terms on real bytecode (the platform's anvil suite and the deploy's smoke).

IMAGE_BOARD_MAX_DESCRIPTION_BYTESconst
1000
IMAGE_BOARD_MAX_NAME_BYTESconst
100

What `initialize` accepts of a board's name and description, in UTF-8 bytes (spec §13.3).

imageBoardTextProblemfunction
(name: string, description: string) => "name" | "description" | null

Which of the two `initialize` would refuse, or null: counted in bytes, as the contract counts.

PermitSignatureinterface
interface PermitSignature { deadline: bigint; v: number; r: Hex; s: Hex; }
permitTypedDatafunction
(o: { token: Address; tokenName: string; chainId: number; owner: Address; spender: Address; value: bigint; nonce: bigint; deadline: bigint; }) => { domain: { name: string; version: string; chainId: number; verifyingContract: `0x${string}`; …

The EIP-2612 permit a buyer signs for the total they were shown, with the board as spender.

pokeDuefunction
(rental: Pick<BlockRental, "expiry" | "tenantHash" | "poked">, now: bigint) => boolean

Whether `poke` would go through at `now` (the chain's time): a lapsed term, a tenant picture, not yet poked.

splitSignaturefunction
(signature: Hex, deadline: bigint) => PermitSignature

Splits a 65-byte signature into the `v, r, s` a permit buy takes.

Resale (IMAGE-BOARD-SPEC.md §7a)

the whole block, at its owner's price

buildDelistBlockfunction
(o: { board: Address; tokenId: bigint; }) => CallRequest<"delistBlock", [bigint]>
buildListBlockfunction
(o: { board: Address; tokenId: bigint; price: bigint; }) => CallRequest<"listBlock", [bigint, bigint]>

`listBlock`: put the block up for sale at `price`, or change the price. The owner alone.

Renting (IMAGE-BOARD-SPEC.md §12, 2026-10-20)

a term of a block, prepaid, streamed to its owner

blockRentQuotefunction
(ratePerDay: bigint, durationSecs: bigint) => { cost: bigint; protocolCut: bigint; royalty: bigint; net: bigint; }

What a term of `durationSecs` at `ratePerDay` costs and where it goes, composed as `rent` composes it: the page boards' `rentCost` and `rentSplit` with the protocol's 5% and the board holder's 5%.

buildBuyListedBlockWithPermitfunction
(o: { board: Address; tokenId: bigint; recipient: Address; expectedPrice: bigint; permit: PermitSignature; }) => CallRequest<"buyListedBlockWithPermit", [bigint, Address, bigint, bigint, number, Hex, Hex]>

`buyListedBlockWithPermit`: one signature (`permitTypedData` for exactly `expectedPrice`) plus one transaction. `expectedPrice` is the price the buyer was SHOWN; the contract refuses any other.

buildClaimRentfunction
(o: { board: Address; tokenIds: readonly bigint[]; }) => CallRequest<"claimRent", [readonly bigint[]]>

`claimRent`: credits each block's owner what has streamed to them. Permissionless; pays only owners.

buildEditRentedfunction
(o: { board: Address; tokenId: bigint; contentHash: Hex; }) => CallRequest<"editRented", [bigint, Hex]>

`editRented`: the tenant's picture for their term. The owner's picture is untouched.

buildExtendRentalWithPermitfunction
(o: { board: Address; tokenId: bigint; durationSecs: bigint; expectedRatePerDay: bigint; permit: PermitSignature; }) => CallRequest<"extendRentalWithPermit", [bigint, bigint, bigint, bigint, number, Hex, Hex]>

`extendRentalWithPermit`: the tenant's term becomes `durationSecs` from now, at the current rate.

buildListForRentfunction
(o: { board: Address; tokenId: bigint; ratePerDay: bigint; maxDurationSecs: bigint; }) => CallRequest<"listForRent", [bigint, bigint, bigint]>

`listForRent`: offer the block at `ratePerDay` for terms up to `maxDurationSecs`; a rate of zero ends the offer.

buildRentBlockWithPermitfunction
(o: { board: Address; tokenId: bigint; tenant: Address; durationSecs: bigint; expectedRatePerDay: bigint; permit: PermitSignature; }) => CallRequest<"rentWithPermit", [bigint, Address, bigint, bigint, bigint, number, Hex, Hex]>

`rentWithPermit`: one signature (`permitTypedData` for exactly `blockRentQuote(rate, term).cost`) plus one transaction. `tenant` is named — whoever pays need not be them. `expectedRatePerDay` is the rate the payer was SHOWN; the contract refuses any other.

rentalLivefunction
(rental: Pick<BlockRental, "expiry">, now: bigint) => boolean

Whether a tenancy is live at `now` (the chain's time, never the machine's): it ends AT `expiry`.

rentUnclaimedfunction
(rental: BlockRental, now: bigint) => bigint

Rent streamed to the owner and not yet credited: what `claimRent` would credit at `now`.

From image-grid.ts

The image-board grid rule, in TypeScript (`docs/IMAGE-BOARD-SPEC.md`).

blockErrorfunction
(state: GridState, rect: Rect, now: bigint) => BlockErrorName

`buyError` for one rectangle.

BlockErrorNametype
type BlockErrorName = | 'none' | 'EmptyBlock' | 'OutsideGrid' | 'CellsTaken' | 'CellsKept' | 'CoolingDown' | 'TooLarge' | 'TooManyBlocks';

The contract's error names, and `none` for a buy that can go through.

buyErrorfunction
(state: GridState, rects: readonly Rect[], now: bigint) => BlockErrorName

Why `buyBlocks` would refuse these rectangles bought together at `now`, or `none`.

CELL_SIZESconst
readonly [10, 15, 20]
CellMaptype
type CellMap = Uint32Array;

Which block holds each cell, `cells[row * grid.cols + col]`; zero is a free cell.

cellMapFromBlocksfunction
(grid: Grid, blocks: readonly (Rect & { tokenId: bigint | number | string; })[]) => CellMap

The cell map from the blocks alone: every block's rectangle painted in id order. Exactly the contract's, because `_record` is the only thing that writes a cell, and it paints a new block's whole rectangle — so a screen holding the blocks needs no `cellRow` read. Pass every block.

cellMapOffunction
(grid: Grid, rows: readonly (readonly bigint[])[]) => CellMap

The cell map from what the contract's `cellRow` answers for each row in order: ⌈cols / 8⌉ words a row, column `c` in word `c / 8`, lane `c % 8`, 32 bits a lane.

CELLS_PER_WORDconst
8

Cells to a storage word of the cell map.

CellSizetype
type CellSize = (typeof CELL_SIZES)[number];
emptyCellsfunction
(grid: Grid) => CellMap

A board with nothing sold.

FULL_PRICE_BPSconst
10000

A board's `priceBps` before its holder lowers anything: every square at the price set at creation.

Gridinterface
interface Grid { cols: number; rows: number; }
gridOffunction
(width: number, height: number, cellSize: number) => Grid | { error: "InvalidConfig"; }

The grid an image of this size gets: whole cells from the top-left, the strip a cell does not fit left unsold. `InvalidConfig` is the contract's refusal, for the same inputs.

GridStateinterface
interface GridState { grid: Grid; /** Every cell outside a zone. Zero keeps them: the board sells only its priced zones. */ cellPrice: bigint; /** Required, `[]` for none: leaving them out would price a board at a price it does not charge. …

Everything a buy is checked and priced against.

Holdinginterface
interface Holding { owner: string; /** What the block cost over the creation price of its cells, in bps, rounded up. */ level: bigint; /** When it was bought, in seconds. A resale or a gift does not move it. */ boughtAt: bigint; }

What pricing a take needs to know of a block.

idAtfunction
(cells: CellMap, grid: Grid, col: number, row: number) => number

The block holding a cell, or zero.

LAYOUT_ERRORconst
Record<LayoutProblem, "InvalidConfig">

The error the contract's `initialize` reverts with for each, which the vectors pin.

layoutProblemfunction
(grid: Grid, cellPrice: bigint, zones: readonly Zone[]) => { problem: LayoutProblem; index: number; } | null

The contract's checks on a new board's prices, in its order: the count of zones, then each zone (its size, then the grid, then the zones before it), then whether anything is left for sale. `index` is the zone's place in its list, `-1` when no one zone is to blame; null means the contract would accept them. A price of zero is not refused anywhere: it keeps cells.

LayoutProblemtype
type LayoutProblem = 'too-many-zones' | 'zone-empty' | 'zone-outside' | 'zones-overlap' | 'nothing-for-sale';

Why a board's prices and zones would be refused at creation, naming which zone.

MAX_BLOCKS_TAKEN_PER_BUYconst
88

The contract's `MAX_BLOCKS_TAKEN_PER_BUY`: the most blocks one buy may take cells from, counted once per rectangle.

MAX_CELL_SIZEconst
200
MAX_COOLDOWN_SECSconst
604800
MAX_GRID_COLSconst
256

A block id per cell on chain, eight to a storage word, 32 words to a row.

MAX_GRID_ROWSconst
1000

The contract's limit on rows. A buy is bounded by `MAX_WORDS_PER_BUY`, not by the grid.

MAX_REVERSION_WEEKSconst
52
MAX_TAKE_BPSconst
30000

`TermsLib`'s ceilings, which a board's terms are held to as a page board's are.

MAX_WORDS_PER_BUYconst
512

The contract's `MAX_WORDS_PER_BUY`: the most cell words one buy may write, counted per row of each rectangle as the words its columns span (`wordsOf`). 512 is a 64 × 64 square or a 256 × 16 strip.

MAX_ZONESconst
512

The chain's ceiling, not a product limit: the contract's `MAX_ZONES`, measured to fit a transaction.

MIN_CELL_SIZEconst
10

Square cells, in the image's own pixels: the contract takes any whole size from `MIN_CELL_SIZE` to `MAX_CELL_SIZE` (2026-10-20). `CELL_SIZES` are the ones a set-up screen usually offers.

paintfunction
(cells: CellMap, grid: Grid, rect: Rect, id: number) => void

Marks every cell of `rect` as block `id`'s, as a buy does: what was under it is covered.

quotefunction
(state: GridState, rect: Rect, now: bigint) => bigint

`quoteBlocks` for one rectangle.

quoteBlocksfunction
(state: GridState, rects: readonly Rect[], now: bigint) => bigint

What `buyBlocks` would pull for these rectangles at `now`: the sum of each one's price. Throws `RefusedBuyError` when refused.

quoteRectfunction
(state: GridState, rect: Rect, now: bigint) => RectQuote

One rectangle as if bought alone, with what it covers: the free cells and every block it would take from, each with its price. For a screen; never throws for a refusal, which is `error`.

Rectinterface
interface Rect { col: number; row: number; cols: number; rows: number; }

A block, in cells, from the grid's top-left.

RectQuoteinterface
interface RectQuote { /** Why this rectangle is refused, `none` if it is not. Counted as if it were the buy's only one. */ error: BlockErrorName; /** Its whole price; zero when refused. */ total: bigint; /** Cells nobody holds, sold first-h…

What one rectangle covers and costs, as the contract surveys it.

RefusedBuyErrorclass
typeof RefusedBuyError

Thrown where the contract's `quote` and `quoteBlocks` revert: they never price a refusal.

sellableCellsfunction
(grid: Grid, cellPrice: bigint, zones: readonly Zone[]) => number

How many cells a first buy can take on a board made with these prices: each priced zone's, and every cell outside the zones unless the board's own price is zero. The zones must already be accepted by `layoutProblem` (inside the grid, never overlapping), as the contract counts after checking them.

squarePricefunction
(cellPrice: bigint, priceBps: number) => bigint

What one FREE square costs now, at the board's price or a zone's: rounded up, as one. Zero is a kept square.

TakenPartinterface
interface TakenPart { blockId: number; owner: string; /** How many of its cells the rectangle covers. */ cells: number; /** What those cells cost the buyer. */ price: bigint; }

One covered block's share of a rectangle.

TakeTermsinterface
interface TakeTerms { takeBps: number; payoutBps: number; reversionBps: number; maxReversionWeeks: number; cooldownSecs: number; }

How a sold cell is taken: the board's five terms, chosen by its creator and frozen (`Terms` on chain).

termsErrorfunction
(t: TakeTerms, protocolBps: number) => TermsError | null

Why the contract would refuse these terms at creation, in `TermsLib`'s order, or null. A displaced owner is paid at least the floor (`payoutBps` ≥ 10,000), and a take must leave something for the board's holder after the payout and the protocol's cut.

TermsErrortype
type TermsError = 'PayoutBelowPrincipal' | 'TakeTooHigh' | 'TakeBelowPayout' | 'InvalidReversion' | 'InvalidConfig';

The errors `TermsLib.checkEconomicsAbsolute` reverts a board's creation with.

wordsOffunction
(rect: Rect) => number

The storage words a rectangle writes, which is what `MAX_WORDS_PER_BUY` counts: per row, the words its columns span.

Zoneinterface
interface Zone extends Rect { cellPrice: bigint; }

Cells priced differently from the board's `cellPrice`, in the settlement token's units. Zero keeps them.

From image-compose.ts

The drawn board (`docs/IMAGE-BOARD-SPEC.md` §13.9): what every renderer draws, in TypeScript, on raw RGBA.

acceptedPictureSizesfunction
(box: { width: number; height: number; }) => [{ width: number; height: number; }, { width: number; height: number; }]

The two sizes a block's picture may be: its rectangle's, or half of each side rounded (at least 1).

blockBoxfunction
(rect: Pick<Rect, "cols" | "rows">, cellSize: number) => { width: number; height: number; }

A block's rectangle in pixels.

composeBoardfunction
(o: { source: RgbaPicture; cellSize: number; grid: Grid; cells: CellMap; blocks: readonly ComposedBlock[]; }) => Uint8ClampedArray

The board as drawn: a new RGBA buffer the source's size. `blocks` in any order: the cell map gives each cell to one block, so no two pictures meet on a pixel and the order cannot matter (the spec's "in id order" is how the map is painted, `cellMapFromBlocks`). A picture whose size is neither of `acceptedPictureSizes` is skipped, as spec §13.9 says.

ComposedBlockinterface
interface ComposedBlock extends Rect { /** The block's id: the cell map names cells by it. */ tokenId: number; /** Its SHOWN picture, decoded and checked against its hash by the caller; null for none. */ picture: RgbaPicture | null; }
RgbaPictureinterface
interface RgbaPicture { width: number; height: number; rgba: Uint8Array | Uint8ClampedArray; }

Pixels, row-major, four bytes each, straight alpha.

From content.ts

Content addressing — spec §3, LOCKED.

cidBytesToStringfunction
(cid: Hex) => string

Any binary CID — `0x01…`, a CIDv1 of any codec — as its base32 string (`b…`). An image board's source picture is too large for one raw block, so its address is a CID of its own rather than its hash (`IMAGE-BOARD-SPEC.md` §13.7); this is how a reader writes it. The same encoder as `contentHashToCid`, which is this applied to the raw-block prefix and the hash.

cidStringToBytesfunction
(cid: string) => Hex

A CIDv1 string (`b…`, base32) as its binary bytes: what an image board's `sourceCid` holds. The inverse of `cidBytesToString`, with the same refusals — so a pinning service's answer goes on chain only if it reads back as the string it was.

contentHashToCidfunction
(hash: Hex) => string

Renders a `bytes32` content hash as the IPFS CIDv1 raw block that addresses the same bytes.

Other

IMAGE_BOARD_ABIconst
Abi
IMAGE_BOARD_COLLECTION_ABIconst
Abi
IMAGE_BOARD_RENDERER_ABIconst
Abi