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_DENOMINATORconst10000nThe TypeScript twin of `packages/websitekit-contracts/src/Pricing.sol`.
BuyBreakdowninterfaceinterface BuyBreakdown extends TakeQuote, Split {}computeBuyBreakdownfunction(lastPrice: bigint, basePrice: bigint, elapsedWeeks: bigint, economics: SiteEconomics, isUnclaimed: boolean) => BuyBreakdownWhat 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) => bigintMirrors `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) => SplitMirrors `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) => TakeQuoteMirrors `Pricing.computeTakePrice`.
PricingOverflowErrorclasstypeof PricingOverflowErrorThrown 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_WEEKconst604800nSiteEconomicsinterfaceinterface SiteEconomics { takeBps: bigint; payoutBps: bigint; reversionBps: bigint; maxReversionWeeks: bigint; protocolBps: bigint; }A site's take economics, in the SDK's own vocabulary.
Splitinterfaceinterface 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…TakeQuoteinterfaceinterface 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) => bigintMirrors `Pricing.askCeiling` — spec §3.2. The highest ask an owner may post.
resolveReversionBasefunction(askFloor: bigint, lastPrice: bigint) => bigintMirrors `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) => AccrualBoth 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.
Accrualinterfaceinterface 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) => bigintMirrors `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_DURATIONconst3600nThe shortest term the contract will open or extend (§2.5.3).
quoteRentfunction(ratePerDay: bigint, durationSecs: bigint, protocolRentBps: bigint, feeBps: bigint) => RentQuoterentCostfunction(ratePerDay: bigint, durationSecs: bigint) => bigintMirrors `RentalsLib.rentCost`. Gross rent for a term.
RentQuoteinterfaceinterface 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) => RentSplitMirrors `RentalsLib.rentSplit` — spec §2.5.
RentSplitinterfaceinterface 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_DAYconst86400nSeconds 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) => stringAny 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) => HexThe 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.
ContentFailuretypetype 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) => stringRenders a `bytes32` content hash as the IPFS CIDv1 raw block that addresses the same bytes.
ContentKindtypeContentKind = { 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.
ContentResulttypetype ContentResult = | ({ ok: true } & DecodedContent) | { ok: false; reason: ContentFailure; schemeVersion?: number };ContentTooLargeErrorclasstypeof ContentTooLargeErrordecodeContentfunction(bytes: Uint8Array) => DecodedContentSplits an object into its header and payload. Does NOT verify the hash — use `readContent` for anything that will be rendered.
DecodedContentinterfaceinterface DecodedContent { schemeVersion: number; kind: number; payload: Uint8Array; }DecodedLinkedinterfaceinterface 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) => DecodedLinkedReads 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) => EncodedContentWraps a payload in the scheme header and hashes it.
EncodedContentinterfaceinterface 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) => EncodedContentencodeLinkfunction(href: string, label?: string) => EncodedContentA link payload is JSON — `{"href": "…"}`, optionally with a `"label"`.
encodeLinkedfunction(innerKind: number, href: string, body: Uint8Array) => EncodedContentWraps a body of another kind with a destination.
encodeTextfunction(text: string) => EncodedContentUTF-8 bytes, unsanitized and unescaped — see the module note on why that is correct here.
HEADER_BYTESconst2The header is two bytes: `[schemeVersion][kind]`.
MalformedContentErrorclasstypeof MalformedContentErrorMAX_OBJECT_BYTESconst1048576**Enforced at encode time, so it bites before anyone signs.**
readContentfunction(bytes: Uint8Array, expectedHash: Hex) => ContentResultThe one function a renderer should call. Verify, then decode, in that order and never the other way round.
SCHEME_VERSIONconst1Bumping 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_MINconst128Kind ids at or above this are reserved for the site and never interpreted by websitekit.
Slot identity
keys, not ordinals (§2).
assertValidSlotKeyfunction(key: string) => voidValidates 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.
InvalidSlotKeyErrorclasstypeof InvalidSlotKeyErrorMAX_KEY_LENGTHconst128Long 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) => bigintThe ERC-721 token id for a slot, for wallet and marketplace links.
Reads
one call per page, through `SlotReader` (§5, §11.4).
BuyContextinterfaceinterface 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) => SiteEconomicsThe subset of a site's terms the pricing twin needs, mapped without hand-copying five bps fields.
isTokenSettledfunction(terms: Pick<SiteTerms, "settlementToken">) => booleanWhether a site settles in an ERC-20 rather than the chain's native currency.
Listinginterfaceinterface 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).
Rentalinterfaceinterface 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_ABIconstAbi`RentalsLib`'s ABI. Needed on its own only rarely; what most callers want is `SITE_EVENTS_ABI`.
SITE_EVENTS_ABIconstAbi**The ABI to watch a site's logs with.**
SiteRefinterfaceinterface SiteRef { site: Address; reader: Address; }Where to read a site from.
SiteTermsinterfaceinterface 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_ABIconstAbiThe convenience-view periphery. Redeployable — see the module note.
SLOT_SITE_ABIconstAbiThe committed `SlotSite` ABI, typed for viem. Kept in sync by `pnpm sync:abi`.
SlotStateinterfaceinterface 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]> | nullThe 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`.
BuildBuyOptionsinterfaceinterface 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`.
BuildCreateSiteOptionsinterfaceinterface 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.
BuildRentOptionsinterfaceinterface 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.
CallRequestinterfaceinterface 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_SECSconst300nHow 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_BPSconst100nSlippage 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_ABIconstreadonly [{ 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.
InvalidEconomicsErrorclasstypeof InvalidEconomicsErrorisNativeSettlementfunction(settlementToken: Address) => boolean`0x0` is native settlement; anything else is an ERC-20 whose `msg.value` must be exactly zero.
SiteEconomicsConfiginterfaceinterface 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.
SiteFloorPolicyConfiginterfaceinterface 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.
SiteRentalConfiginterfaceinterface 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_ABIconstAbi
Render escrow
one vault per board, outside `SlotSite`; the pin is all it needs from bytecode.
ATTESTOR_ABIconstAbibuildApproveVaultfunction(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`.
BuildCreateEscrowedSiteOptionsinterfaceinterface 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_ABIconstAbiESCROW_VAULT_ABIconstAbiEscrowBindinterfaceinterface 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…EscrowParamsinterfaceinterface 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.
VaultDepositinterfaceinterface 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…VaultStateinterfaceinterface 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).
Chaininterfaceinterface 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) => ChainThe chain with this id, or a refusal naming the ones there are.
CHAINSconstRecord<number, Chain>CONTENT_KIND_BY_NAMEconstRecord<SlotKindName, number>DEFAULT_CONTENT_GATEWAYfunction(cid: string) => stringDEFAULT_SETTLEMENT_DECIMALSconst18Decimals a floor string is parsed against when the config does not say otherwise.
defineSitefunction(input: DefineSiteInput) => SiteConfigValidates a site config and normalizes it into the shape every consumer wants.
DefineSiteInputinterfaceinterface 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…InvalidSiteConfigErrorclasstypeof InvalidSiteConfigErrorNATIVE_CURRENCYconstSettlementCurrencyNative settlement on every chain this SDK names.
parseFloorfunction(amount: string, decimals?: number) => bigintParses 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_CHAINconstChainRobinhood 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_USDGconstSettlementTokenThe 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_CHAINconstChainRobinhood Chain testnet — free money, a mintable stand-in dollar, and every seeded example board.
ROBINHOOD_TESTNET_TUSDconstSettlementToken`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_TOKENSconstRecord<number, SettlementToken>SettlementCurrencyinterfaceinterface SettlementCurrency { symbol: string; decimals: number; }What a board's prices are counted in, for showing a person a number.
SettlementTokeninterfaceinterface 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) => SettlementTokenThe 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.
SiteConfiginterfaceinterface 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…SlotDefinitioninterfaceinterface SlotDefinition { key: string; kind: SlotKindName; contentKind: number; floor: bigint; }SlotDefinitionInputinterfaceinterface 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.
SlotKindNametypetype 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_SITESconstRecord<number, `0x${string}`>The scaffold's demo board on each chain, keyed by chain id.
demoSiteForfunction(chainId: number) => Address | undefinedDeploymentinterfaceinterface 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) => DeploymentDEPLOYMENTSconstRecord<number, Deployment>ESCROW_DEPLOYMENTSconstRecord<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_CHAINconstRecord<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> | undefinedROBINHOOD_MAINNETconstDeployment**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_TESTNETconstDeployment**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_R2constDeploymentThe 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_DEPLOYMENTSconstReadonly<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.
ImageBoardDeploymentinterfaceinterface 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) => ImageBoardDeploymentThe 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_BOARDSconstImageBoardDeploymentRobinhood 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_BOARDSconstImageBoardDeploymentRobinhood 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_SECSconst31536000nIMAGE_BLOCK_MIN_RENTAL_SECSconst3600nThe shortest and longest term a block can be rented for: `MIN_RENTAL_DURATION`, `MAX_RENTAL_TERM`.
IMAGE_BLOCK_RENT_ROYALTY_BPSconst500nWhat a rental pays whoever holds the board's NFT then, beside the protocol's cut: `ImageBoard.RENT_ROYALTY_BPS`.
IMAGE_BLOCK_RESALE_ROYALTY_BPSconst500nWhat a block's resale pays whoever holds the board's NFT then: `ImageBoard.RESALE_ROYALTY_BPS`.
IMAGE_BOARD_PROTOCOL_BPSconst500nThe protocol's cut of every square sold and every block resold. The deploy script refuses any other.
IMAGE_BOARD_ROYALTY_BPSconst500nERC-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_BPSconstbigintWhat 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
BlockRentalinterfaceinterface 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.
BlockRentListinginterfaceinterface BlockRentListing { ratePerDay: bigint; maxDurationSecs: bigint; }BlockStateinterfaceinterface 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) => GridStateThe 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.
ImageBoardStateinterfaceinterface 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) => booleanWhether `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.
ReadAtinterfaceinterface 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">) => stringThe 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.
CreateImageBoardOptionsinterfaceinterface 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_PARAMSconstreadonly [{ 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_BYTESconst1000IMAGE_BOARD_MAX_NAME_BYTESconst100What `initialize` accepts of a board's name and description, in UTF-8 bytes (spec §13.3).
imageBoardTextProblemfunction(name: string, description: string) => "name" | "description" | nullWhich of the two `initialize` would refuse, or null: counted in bytes, as the contract counts.
PermitSignatureinterfaceinterface 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) => booleanWhether `poke` would go through at `now` (the chain's time): a lapsed term, a tenant picture, not yet poked.
splitSignaturefunction(signature: Hex, deadline: bigint) => PermitSignatureSplits 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) => booleanWhether a tenancy is live at `now` (the chain's time, never the machine's): it ends AT `expiry`.
rentUnclaimedfunction(rental: BlockRental, now: bigint) => bigintRent 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.
BlockErrorNametypetype 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) => BlockErrorNameWhy `buyBlocks` would refuse these rectangles bought together at `now`, or `none`.
CELL_SIZESconstreadonly [10, 15, 20]CellMaptypetype 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; })[]) => CellMapThe 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[])[]) => CellMapThe 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_WORDconst8Cells to a storage word of the cell map.
CellSizetypetype CellSize = (typeof CELL_SIZES)[number];emptyCellsfunction(grid: Grid) => CellMapA board with nothing sold.
FULL_PRICE_BPSconst10000A board's `priceBps` before its holder lowers anything: every square at the price set at creation.
Gridinterfaceinterface 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.
GridStateinterfaceinterface 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.
Holdinginterfaceinterface 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) => numberThe block holding a cell, or zero.
LAYOUT_ERRORconstRecord<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; } | nullThe 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.
LayoutProblemtypetype 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_BUYconst88The contract's `MAX_BLOCKS_TAKEN_PER_BUY`: the most blocks one buy may take cells from, counted once per rectangle.
MAX_CELL_SIZEconst200MAX_COOLDOWN_SECSconst604800MAX_GRID_COLSconst256A block id per cell on chain, eight to a storage word, 32 words to a row.
MAX_GRID_ROWSconst1000The contract's limit on rows. A buy is bounded by `MAX_WORDS_PER_BUY`, not by the grid.
MAX_REVERSION_WEEKSconst52MAX_TAKE_BPSconst30000`TermsLib`'s ceilings, which a board's terms are held to as a page board's are.
MAX_WORDS_PER_BUYconst512The 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_ZONESconst512The chain's ceiling, not a product limit: the contract's `MAX_ZONES`, measured to fit a transaction.
MIN_CELL_SIZEconst10Square 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) => voidMarks 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) => bigintWhat `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) => RectQuoteOne 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`.
Rectinterfaceinterface Rect { col: number; row: number; cols: number; rows: number; }A block, in cells, from the grid's top-left.
RectQuoteinterfaceinterface 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.
RefusedBuyErrorclasstypeof RefusedBuyErrorThrown where the contract's `quote` and `quoteBlocks` revert: they never price a refusal.
sellableCellsfunction(grid: Grid, cellPrice: bigint, zones: readonly Zone[]) => numberHow 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) => bigintWhat one FREE square costs now, at the board's price or a zone's: rounded up, as one. Zero is a kept square.
TakenPartinterfaceinterface 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.
TakeTermsinterfaceinterface 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 | nullWhy 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.
TermsErrortypetype TermsError = 'PayoutBelowPrincipal' | 'TakeTooHigh' | 'TakeBelowPayout' | 'InvalidReversion' | 'InvalidConfig';The errors `TermsLib.checkEconomicsAbsolute` reverts a board's creation with.
wordsOffunction(rect: Rect) => numberThe storage words a rectangle writes, which is what `MAX_WORDS_PER_BUY` counts: per row, the words its columns span.
Zoneinterfaceinterface 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[]; }) => Uint8ClampedArrayThe 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.
ComposedBlockinterfaceinterface 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; }RgbaPictureinterfaceinterface 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) => stringAny 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) => HexA 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) => stringRenders a `bytes32` content hash as the IPFS CIDv1 raw block that addresses the same bytes.
Other
IMAGE_BOARD_ABIconstAbiIMAGE_BOARD_COLLECTION_ABIconstAbiIMAGE_BOARD_RENDERER_ABIconstAbi