Keep the work.
Check every byte.

How KEEL fits together

Five components store, check and open the work. Three more handle the collectible token. Each one does a single job.

This guide follows one example throughout. Tidal Study is a fictional generative drawing: a small p5.js sketch that depends on one specific version of the p5 library.

What makes KEEL different

A token that links to a file records where the file was. A KEEL work records exactly what the work is.

• Identified by content, not location. Each file is known by its fingerprint (Mark), so a copy from any source can be checked.
• Dependencies stored once, pinned per work. Many works share one stored library, and a new release never changes an existing work.
• Checked before it runs, isolated while it runs. The artwork can't mark itself as verified or reach a wallet.
• One model on every chain. Ethereum and Tezos use the same components and terms.

Runtimes

A runtime is the program that opens a kind of work, such as a drawing library, a game engine or a media player. Everything the runtime needs is declared and travels with the work.

Parts & modules

A Part is a reusable component a work depends on, such as a library, decoder, model or data file. Each Part has its own identity, version and reuse terms. The SDK calls them modules.

You find a Part by name and bind it by Mark. A name like "p5" tells you what it does. Its Mark, the fingerprint of its bytes, tells you exactly which build you selected. Every work that uses it points to the same stored copy.

• Binding. A work binds each Part by stored object ID, Mark and size on the selected chain. If a dependency can't be resolved exactly, preparation stops.
• Reuse terms. Each Part carries its own license (open, paid, restricted or submission-based).
• Inlays. An Inlay is an attached component that contributes to another work, such as an item equipped on a game character. It keeps its own identity, and the host work's rules still apply.

The Hold

The Hold is KEEL's native onchain storage. It cuts files into small pieces, stores them, records the order for joining them, and checks the result on the way back out.

• One work = many objects. The sketch, the library, music, models and textures are stored as separate objects. Welds join pieces or smaller objects into larger ones. Together they form the object graph, which is the work's assembly plan.
• Reuse. If twenty works use the same exact library, they all point to one library object in the Hold, and each work only adds its own sketch. You only pay to store a Part if it isn't already on that network.
• Immutable. Stored content objects never change. A new version is a new object with a new Mark (see Revisions).

Carriers

A carrier is where a file's bytes are kept. Carriers differ in what has to stay online, and every carrier is checked the same way.

Inline, Hybrid & Raw

Storage decides where the bytes live. Delivery decides how they reach the browser. These are separate choices, and Inline and Hybrid can both read from the same native Hold.

• Inline puts together one complete document from stored Shell fragments, shared Parts and your file.
• Direct media. A standalone image, video or self-contained 3D model uses the original file and the registered display Part.

The SDK recommends Inline or Hybrid from the measured size (see read size). The final choice is yours.

Shell, Harness & Cage

The Shell checks the work's files, then runs the creator's code inside the Cage, an isolated browser frame. The checks stay outside the Cage, so the artwork can't change its own verdict.

How a work opens

1. Resolve the committed canonical Shell and the work's exact object graph.
2. Check the stored lengths and Marks.
3. Decode within the declared limits, then check the decoded lengths and Marks.
4. Mount the creator content in an opaque child iframe (the Cage).

Presentation choices

The standard Shell is shared. Each work references the registered copy and doesn't pay to upload its own player. The host still has the final say: it controls which scripts, media and network requests can run on its page. That's why one Slab can be interactive in one gallery and show only a thumbnail in another.

Permissions: Guard, Knock, Accord

A Guard declares what the work may do. A Knock is a request from the work across the Seam, and the request alone grants nothing. The Accord is the set of permissions that the artist, the included Parts, the host and the chain all allow. The strictest one wins.

Verification

A Mark is a fingerprint (hash) computed from a file's bytes. The Crucible recomputes the Mark for every recovered file and compares it, along with the file size, to what the work declared.

SHA-256, computed in your browser. One changed word changes the whole fingerprint. A full check (a Pour) also verifies sizes, and the files that pass (the Haul) are what the work opens with.

Verdicts

Collections & minting

A Die is the collection contract. It mints Slabs, the tokens collectors hold, under release rules that are set separately from the Die.

KEEL's creator factory deploys a separate, immutable contract for each creator, owned by whoever created it. A shared ERC-1155 contract is the alternative: each creator's items get their own ID range.

Release rules

Resale. KeelMarket handles ERC-721 resale in native ETH. A listed token sits in escrow until it's bought or the listing is cancelled. A sale moves the token. Supply and the stored work don't change.

Launch workflow

The launchpad ties the artwork, the collection, the mint rules and the collector page into one release plan. You can rehearse the whole release on a test network, which keeps its own separate tokens and records.

Costs & read size

You pay to store new bytes only. Separately, everything a token returns must fit in one read, and that decides whether a work uses Inline or Hybrid.

FRAY auctions

FRAY is an auction between one bidder and a coalition of patrons. If the bidder wins, the work is released as a unique token. If the coalition clears the target, it's released as an edition.

Assumes equal pricing, enough edition supply, and no rounding. Real auctions follow their published terms.

The clearing rule

Each patron declares a maximum contribution, called a cap. The coalition clears if some group of patrons can each afford the same share of the target: the target divided by the group size. With four patrons capped at 25, a target of 100 clears at 25 each. A fifth patron capped at 10 would lower the share to 20, which is more than their cap, so they're left out.

Revisions & freezes

Changing a work creates a new revision. Earlier revisions stay identifiable, and unchanged files are reused rather than stored again.

A freeze applies to one specific thing

Hold objects never change. Registries only ever add revisions.

Adding a storage copy. A large work can use an external carrier now and add a native onchain copy later. Because the Marks are the same, the new copy is provably the same work.

Preserving existing work

Onchaininator recovers the files an existing token points to and stores checked copies with KEEL. Each copy stays linked to the original collection and token.

1. Find the actual files. Follow the token's metadata to the original artwork, scripts and Parts. A preview image may not be the full-resolution or interactive work. Record any missing or unsupported files explicitly.
2. Store checked copies. Keep the original network, contract, token ID and source URI beside the preserved objects.
3. Respect the original contract. If it can't be updated, the preserved copy is recorded separately and linked to it.

Ethereum, Tezos & Anchors

The components and their jobs are the same on both chains. What differs is the underlying machinery: contract language, storage format, token interface and wallet operations.

Every network is separate, EVM networks included. A Part published on Sepolia doesn't exist on Base, even at an address that looks identical.

Anchors: one work, several chains

The evidence behind an Anchor is either checked directly, verified from chain proofs, or vouched for by named attestors. Cross-chain minting is a separate, opt-in operation.

Index, search & profiles

The Index is an onchain protocol record of a work's inventory. The site's indexer is separate software that follows contract events so it can serve search results. Search can fall behind the chain, but the chain itself is always current.

Artist profiles

A profile has a username, public name, bio and image. It's tied to the artist's creator account, so every collection that account creates links back to it. Artists admitted to the platform's program carry an Approved label.

SDK

The SDK gives your code the same functions the KEEL interfaces use. It can describe a project, check inputs, resolve Parts, build previews and prepare contract data for review.

Plan a project

Describe what you know. The planner keeps those decisions and returns the questions still open, the modules required and the tools to use next.

import { planKeelProject } from "@keel/sdk/engine";

const plan = planKeelProject({ title: "Tidal Study", outcome: "explore", runtime: "p5" });

console.log(plan.nextQuestions);     // decisions still open
console.log(plan.modules.required);  // p5 + KEEL's seeded-random Part
console.log(plan.nextTools);         // e.g. analysis, library discovery

Next, resolve each required Part to an exact version on the selected chain, build the intended Shell and resource composition, preview it, and keep the identities of both source and output. Anything missing on that chain is reported by name.

Publishing your own Part

A new renderer, decoder or library becomes a reusable Part once it's built, tested against its real dependencies, and given attribution and usage terms. The module CLI prepares it on your machine. plan shows the new bytes and any existing Parts it reuses, and publishing is a separate step.

keel module init ./my-module
keel module build ./my-module
keel module plan ./my-module

Check what a Studio supports

Each Studio publishes the networks, staging limits and publication paths it supports. Read it before uploading or preparing a wallet action.

import { fetchStudioCapabilities } from "@keel/sdk";

async function inspectStudio(studioUrl) {
  const studio = await fetchStudioCapabilities(studioUrl);
  return studio.chains.map(({ network, status, reason }) => ({ network, status, reason }));
}
// Reads capabilities only. Nothing is uploaded or published.

Environment

The source workspace needs Node.js 22+ and pnpm 10.15.0. The root import includes Node-only code. In a web page, import the browser entry point for your task: /engine, /presentation, /contract-controls or /abi. /inline-viewer-graph is for Node-side preparation.

# inside your keel-sdk checkout
pnpm install
pnpm build
# then run examples from a package that links the SDK — no chain publication happens

Chain data

A work can use values read from a contract. For example, a portrait of a game character can glow brighter when the character's health is high, and can show a shield the character has equipped. The SDK reads the values when the work is built and passes them to the artwork as named variables.

• It runs first. A small generated script runs in the data phase (weight −32768), before the runtime and your artwork.
• It's a snapshot. The prepared data records the chainId and blockNumber it was read at. Reopening the build uses those same values. If the work should follow later changes, you have to design a refresh or publish a new revision. Whether the work captures a moment or keeps changing is an artistic decision, so tell collectors which it is.
• Supported types. Static bool, address, bytes32 and integer types. Dynamic strings, bytes and arrays are refused. Wide integers are kept as decimal text.

// The prepared data module runs before this artwork.
const glow = Number(KEEL.data.health) / 100;   // 0 → dim, 1 → full glow
if (KEEL.data.shielded) drawShield();

SDK: readOnchainData performs the reads, buildOnchainDataFragment generates the script, and assertOnchainDataRoundTrip checks what it publishes. The MCP equivalent is keel-onchain-data-prepare.

MCP

MCP (Model Context Protocol) lets an AI assistant call KEEL's tools with structured inputs. The assistant can inspect, build and prepare. Signing always happens in your wallet, outside the assistant.

Request tools/list from your server to see each tool's exact input and output schemas.

Connect

Build the keel-sdk checkout first (see SDK). Then point your MCP client at the built server and your project folder. File operations can't go outside the workspace path.

{
  "mcpServers": {
    "keel": {
      "command": "node",
      "args": [
        "/path/to/keel-sdk/packages/mcp/dist/cli.js",
        "--workspace",
        "/path/to/your-project"
      ]
    }
  }
}

• The scoped Studio credential goes in the server's environment as KEEL_STUDIO_AGENT_TOKEN, never in tool arguments. Draft edits check the expected revision before saving.
• Staging normally selects keel-verification-shell by leaving out viewer. Setting viewer: "none" selects no shell.
• Planning alone needs no Studio endpoint. Staging and drafts do.

Example request

"Inspect my Tidal Study project. Keep my Tezos choice. Find the Parts it needs, tell me which route is supported, and build a local preview. Show me the decisions that are left."

Editor

The desktop editor puts the work, its collection, contract controls, wallets and an assistant in one workspace. Download coming soon

Contract map

KEEL calls its contracts Rites. Each is a set of rules the chain enforces. There are 19 contract module families, grouped below by job. Which ones are deployed varies by chain.

A single job can span several contracts and some browser code. KeelIndex handles active presentation records. KeelArtifactRegistry handles artifact revisions. KeelHarnessRegistry assembles artifact slots and token forks. KeelArtifactTokenRenderer builds metadata for creator collections. The site's search indexer is separate from all of these.

Platform-level settings belong to a manager contract that requires approval from two-thirds of its governors. Creator-owned records, such as collections and creator shells, stay under the creator's control, separate from the platform shells the manager maintains.

Common operations

Reads return existing information. Writes propose a change and need a signed transaction. "Prepare" means building data for you to review later. The same function name can take different inputs in another contract version or on another chain, so check the ABI or the entrypoint schema.

Glossary

Ownership & rules

Rite

KEEL's word for a smart contract: published rules the chain enforces.

Die

The collection contract. It records Slabs, owners or balances, supply and presentation bindings.

Slab

A collectible token in a wallet. It points to a work but doesn't contain it.

FRAY

KEEL's auction: one bidder against a patron coalition.

Storage

Hold

Native onchain storage for file bytes and the instructions for reassembling them.

Slug

One small piece of a larger file, at most 23,000 bytes on EVM.

Ingot

An EVM contract whose code holds one Slug. Tezos uses big_maps instead.

Weld

An ordered join that assembles Slugs or objects into a larger object.

Mark

A file's fingerprint (digest, hash). Change one byte and the Mark changes.

Index

The sealed inventory of a work's pieces and Marks. It isn't the site's search indexer.

Carrier

Where stored bytes are kept and how they're retrieved.

Wake

Experimental recovery from Ethereum transaction history.

Opening & checking

Crucible

The verification layer. It compares recovered files with declared sizes and Marks.

Pour

One run through the Crucible's checks.

Haul

The resources that passed the checks and are used to open the work.

Harness

The composition that runs the work: resources, runtime context, isolated environment.

Shell

The interface that opens around the work. The canonical Shell owns the checks and the K control.

Cage

The isolated browser frame where creator code runs, with no wallet and no open network.

Sleeve

Standard-format metadata that wallets and marketplaces understand.

Permissions

Seam

The checked, limited boundary around the Cage.

Knock

A request made by the work through the Seam. It grants nothing by itself.

Guard

The declared limits on what the work may do.

Accord

The permissions that the artist, Parts, host and chain all allow. The strictest wins.

Reuse & preservation

Parts

Reusable components (modules) with their own identities and terms.

Inlays

Attached components that contribute to another work under its rules.

Anchor

A record tying a revision to evidence on another chain or carrier.

Grip

The number of chains holding an Anchor for a work.

Verdicts

Raw

Not yet checked.

Clean

The declared checks passed.

Stale

Superseded in the current view. It may still be the correct pinned version.

Slag

Failed verification and was rejected.

Burned

Deliberately retired by an authorized action.

General terms

Artifact

An identified work, separate from any token pointing to it.

Revision

One recorded version of a work or presentation.

Manifest

The structured inventory of files, their Marks and how they relate.

Metadata

Descriptive information and media references for a work or token.

RPC

A service that apps use to read a chain or send operations to it.

ABI

The machine-readable list of an EVM contract's functions and inputs.

Receipt / read-back

Proof a transaction was included / fetching and checking the actual result.

Seed

A recorded input that makes a generative result reproducible.

Troubleshooting

Start from what you can see. Always keep your original files, your selected network and the existing recovery record.

The work or a Part won't load

Other problems

Reporting an issue

Include the guide or operation you followed, the network, the work revision, public contract and token references, the resource that failed, the exact error, and whether it happens locally or only in a particular host. Never include signing secrets or private credentials.