# COLORGASM — a fully onchain edition, built as a Manifold extension COLORGASM (`CLGSM`) is a 100-piece edition minted on a Manifold creator contract, with its metadata and images hosted on Arweave. This repository is the machinery that moves the artworks themselves into Ethereum contract code, and lets each holder swap their Arweave-era token for a fully onchain one. It is three small Solidity contracts, a set of Node scripts that drive them, and the Python encoder that turns a 60 MB PNG into an AVIF small enough to live onchain and sharp enough to still be the artwork. The interesting part — and the reason this README exists — is that **the creator contract could not be changed**. Everything here is built inside the one extension point Manifold gives you. ## Deployed on Ethereum mainnet | contract | address | role | | **COLORGASM (`CLGSM`)** creator | [`0x7dC2a81Ba2Bf47548EC2F9645007119dF90ba01b`](https://etherscan.io/address/0x7dC2a81Ba2Bf47548EC2F9645007119dF90ba01b) | the Manifold ERC-721 creator contract — unchanged, not deployed from this repo | | **ColorgasmRedeemExtension** | [`0xCD5ef63FA405786B2ecb498F83687f6a566CF374`](https://etherscan.io/address/0xCD5ef63FA405786B2ecb498F83687f6a566CF374) | the extension: burn/redeem, artwork pointers, `tokenURI` | | **ColorgasmStorage** | [`0xE43f8FAC380616bf15968be038eF00Bc01514c00`](https://etherscan.io/address/0xE43f8FAC380616bf15968be038eF00Bc01514c00) | the artwork bytes, as SSTORE2 chunks | | **ColorgasmRendererV3** | [`0x57a2e9e9a327483A18a37E29F6EF36b96C6Fb5b6`](https://etherscan.io/address/0x57a2e9e9a327483A18a37E29F6EF36b96C6Fb5b6) | assembles the token document | Deployed at block 25,963,689, source verified on Etherscan. Live configuration: artwork stored **raw** (the renderer base64s it at read time), document served as `data:application/json;utf8,`. The same three addresses are recorded in [`deployments/mainnet.json`](deployments/mainnet.json), which every script in this repo reads instead of taking addresses on the command line. ## 1. The constraint: a contract you cannot change `CLGSM` is a Manifold **creator contract** — a proxy onto Manifold's ERC-721 Creator Core. The original 100 tokens were minted through Manifold's edition extension, and their `tokenURI` is an Arweave prefix plus the token index. That contract is immutable: there is no admin function that rewrites those URIs, no upgrade path, no way to reach inside and replace what token #57 points at. So a fully onchain COLORGASM cannot be a migration of the old tokens. It has to be a **new token that the holder chooses to mint, by destroying the old one** — and that new token has to get its `tokenURI` from somewhere the creator contract is willing to ask. That "somewhere" is an extension. ## 2. What a Manifold extension actually is This is the core mechanism, and it is simpler than it sounds. Manifold's Creator Core has a registry of **extension contracts**. An extension is an ordinary contract you deploy yourself. Once the creator's owner or admin calls creator.registerExtension(address(extension), ""); three things become true: **1. The extension can mint.** `creator.mintExtension(to)` mints a new token on the creator contract and records that this extension minted it (`creator.tokenExtension(tokenId)`). The token is a real `CLGSM` token: same contract, same collection, same royalties, same everything a marketplace sees. **2. The creator asks the extension for the token's metadata.** On every `tokenURI(tokenId)` call, Creator Core looks up which extension minted that token and, **via ERC-165**, asks whether that extension implements `ICreatorExtensionTokenURI`: interface ICreatorExtensionTokenURI { function tokenURI(address creator, uint256 tokenId) external view returns (string memory); // interfaceId == bytes4(keccak256("tokenURI(address,uint256)")) If it does, the creator **delegates** — it calls back into the extension and returns whatever string comes out. That single delegation is the whole hinge of this project: it is the only way to make an immutable creator contract serve a `tokenURI` that is computed from bytes stored in code, and it applies only to tokens the extension itself minted. The old tokens are untouched. **3. The extension can burn, with permission.** `creator.burn(tokenId)` works for an owner-or-approved caller, so the extension can destroy an original — but only once the holder has approved it. Nothing here can take a token. What an extension **cannot** do is equally important: it cannot change the `tokenURI` of tokens it did not mint, it cannot alter the creator's royalties or name, and it cannot register itself. Registration is a deliberate act by the HOLDER MARKETPLACE / anyone │ 1. approve(extension, id) │ tokenURI(newId) ▼ ┌──────────────────────┐ ┌─────────────────────────┐ burn(id) │ CLGSM creator core │ │ ColorgasmRedeemExtension │ ───────────────────────► │ (Manifold, immutable)│ │ │ mintExtension(holder) └──────────┬───────────┘ │ artworkKeyOf[id] ──────┼──┐ │ ERC-165 check, │ metadataOf[id] │ │ tokenURI(creator, newId) │ originalOf[newId] │ │ │ delegated back └──────────┬──────────────┘ │ ◄──────────┘ ┌────────────────────────┐ ┌─────────────────────────┐ │ ColorgasmRendererV3 │─►│ ColorgasmStorage │ │ builds the document │ │ SSTORE2 chunks per key │ └────────────────────────┘ └─────────────────────────┘ ## 3. Three contracts, one job each The split is not decoration. Each contract exists because something about it has to be able to change independently of the others — or to never change at ### `ColorgasmRedeemExtension` — authority and bookkeeping The Manifold-facing contract, and the only one the creator contract knows - `creator`, `firstOriginalId`, `editionSize` — immutable, set at deployment - `artworkKeyOf[originalTokenId]` → a `bytes32` storage key. **Not the image** — - `metadataOf[originalTokenId]` → the token's original JSON minus the image fields, stored via SSTORE2. Each redeemed token keeps exactly the name, description and attributes it was minted with. - `originalOf[newTokenId]` / `redeemedTokenOf[originalTokenId]` — the mapping between the burned original and its onchain replacement, in both directions. - `renderer` and `blobStorage` — swappable addresses, until they are locked. Its two public entry points are `burnRedeem(originalTokenId)` and `burnRedeemBatch(uint256[])`. Both check `isRedeemable`, check `ownerOf`, burn, mint, and record. One transaction, ~130k gas, no data arguments — the holder never sends the artwork, because the artwork is already onchain. `isRedeemable(id)` is true only when all five conditions hold: an artwork pointer is set, a metadata fragment is set, the token is not already redeemed, a renderer is configured, and a storage contract is configured. Surface it in any frontend rather than letting holders guess. ### `ColorgasmStorage` — the bytes A deliberately generic, permissionless blob store. Bytes are written under a caller-chosen `bytes32` key, one chunk per transaction, as **SSTORE2** — the data is deployed as contract code, which is the cheapest persistent storage the EVM offers: 200 gas per byte, against 625 for a regular storage slot. append(bytes32 key, bytes calldata chunk) returns (uint256 index) seal(bytes32 key) // irreversible chunksOf(bytes32 key) returns (address[]) // what a renderer reads Two design points worth understanding: - **The first address to write a key owns it.** Nobody can overwrite someone else's blob, and anyone can use the contract for their own work. There is no - **`MAX_CHUNK` is 24,573 bytes** — SSTORE2's 24,575-byte limit rounded down to a multiple of 3 (3 × 8191). The multiple of 3 is what lets base64 be done chunk by chunk at render time: 3 bytes become exactly 4 characters, so 3-aligned chunks encode independently and their encodings concatenate with no `seal(key)` is the promise a collector actually cares about: after it, those bytes can never change, by anyone, ever. ### `ColorgasmRendererV3` — presentation, and the only swappable part Reads the pointer and metadata fragment from the extension, the chunk pointers data:application/json;utf8,{"name":"COLORGASM #057",…,"image":"data:image/avif;base64,…"} in **one exactly-sized buffer**, allocated once, every byte written into its final place and never moved again. Earlier versions built the image, then its base64, then the JSON, then sometimes a base64 of that — four full-size buffers, and the EVM prices memory with the square of how far it stretches. At these image sizes that difference is the difference between a token that renders and Three choices it encodes: - **Raw vs pre-encoded.** `preEncoded` is immutable per deployment. Raw stores the AVIF bytes and base64s them at read time (cheapest to store). Pre-encoded stores the base64 characters and renders by straight `extcodecopy` (33% more to store, 15–20× cheaper to serve). Both produce byte-identical documents. - **UTF-8 vs base64 JSON.** Serving the JSON as UTF-8 rather than base64-ing it again removes the last full-size copy — at 64 KB that alone is 280k gas against 5.15M. Switchable with `setBase64Json`. - **Percent-encoding.** Every COLORGASM name contains a `#`, which starts a URI fragment and would truncate the document at the name. The metadata fragment is escaped; base64 output is URI-safe throughout. The renderer is token-agnostic — it holds no per-token state — so replacing it is a single `setRenderer()` call, until `lockRenderer()`. ## 4. Two numbers that shaped everything **A transaction cannot use more than 16,777,216 gas.** EIP-7825 caps it, whatever the block gas limit is. A maximum-size SSTORE2 chunk costs ~5.53M, so one chunk per transaction is the comfortable shape — and the reason EthFS and ScriptyStorageV2 work the same way. This is why the artwork never passes through the extension: uploading is 41 ordinary transactions for the largest piece, and pointing a token at it afterwards is one ~140k-gas call, however **An `eth_call` gets roughly 50,000,000 gas** on a standard node. That is the budget a marketplace has when it asks for `tokenURI`. Past it the call errors and the token shows as broken. Measured with `npm run ceiling`, on synthetic images at the sizes of the real encodes: | image | store pre-encoded | store raw | **render pre-encoded** | render raw | | 116 KB | 35.0M | 26.2M | **0.4M** | 7.0M | | 250 KB | 75.3M | 56.5M | **1.2M** | 15.4M | | 400 KB | 120.5M | 90.3M | **2.7M** | 25.6M | | 600 KB | 180.6M | — | **5.8M** | — | | 964 KB | 290.1M | — | **14.2M** | — | Every COLORGASM encode renders inside that budget — including the 964 KB one, and not merely within an `eth_call` but inside a single transaction. ## 5. The life of one artwork, end to end CLGSM-57.png 60 MB, 4320 × 7680 │ encode/encode_onchain_v2.py AVIF 4:4:4, constant quality, 1 MB cap COLORGASM_#57.avif ~600 KB │ scripts/upload.js 25 chunks of 24,573 B, one per tx ColorgasmStorage key = bytes32("COLORGASM_57"), then seal() │ scripts/point.js setArtwork(57, key, metadata) ColorgasmRedeemExtension isRedeemable(57) == true │ holder: approve + burnRedeem(57) original burned, new token minted tokenURI(newId) creator delegates → extension → renderer data:application/json;utf8,{…,"image":"data:image/avif;base64,…"} The storage key is readable, not a hash: the ASCII of `COLORGASM_<id>`, right-padded into a `bytes32`. Anyone can recompute it and read the bytes back themselves — see [§9](#9-verifying-it-yourself). Nothing about this order is global. Every token is independent: its own key, its own pointer, its own moment of becoming redeemable. The artist can do one piece completely, stop for a month, and do another. Holders can redeem finished pieces while the rest are still being uploaded. ## 6. Getting a 60 MB PNG under a megabyte `encode/encode_onchain_v2.py` turns the source PNGs into the AVIF files that go onchain. It is Pillow and NumPy only — no shell-out to `avifenc`, no build The policy is **constant quality, capped**: every piece is encoded at one quantiser (`--q`, default 40) so the collection sits on a single visual tier, and fits *down* only when a heavy piece would exceed `--budget` (default 1,000,000 bytes). Light pieces land around 0.4–0.6 MB; only the heavy ones pay the cap. Bytes are spent where the content needs them, not spread evenly. Getting there cheaply is a rate model: `log(bytes)` as a low-order polynomial in the quantiser index, fitted on fast speed-7 probes, then shifted to pass through the real speed-4 encode. That turns what was seven full encodes per image into one, typically with one or two probes. Metrics (PSNR, edge-energy retention, gradient PSNR) are streamed in row bands, so a 33 Mpx image does not need 2.4 GB of float64 copies. Every codec decision in the file header was measured at matched byte size, and the ones that lost are listed there too — 4:2:0 (+7% bytes), 10-bit (+2%), `tune=iq` (+12%), rav1e (+14% and 4× slower), closed-loop residual compensation (+115%). The one thing that wins for this material is a light pre-sharpen (unsharp radius 0.6, 50%): +2.5 points of edge energy for 1.7% more bytes. Edge sharpness is the whole point of these images. The actual collection, from [`encode/report.csv`](encode/report.csv): | encodes | 99 (piece #66 not yet encoded) | | source | 4320 × 7680 each | | per file | 114 KB min, 613 KB mean, 963 KB max | | at the 1 MB cap | 18 of 99 (encoded below q40) | | raw chunks | 2,577 — i.e. 2,577 upload transactions | `encode/convert.sh` is the small companion that produces the pre-encoded (base64) form, with a byte-for-byte round-trip check. `encode/MANIFEST.sha256` is the checksum of every encode as it was uploaded. Measured all-in, with calldata and transaction overhead: **~226 gas per byte** of image stored raw, **~301 gas per byte** stored pre-encoded. | AVIF size | chunks | pre-encoded | @1 gwei | raw | @1 gwei | |---|---|---|---|---|---| | 116 KB | 7 | 34.4M | 0.034 ETH | 26.2M | 0.026 ETH | | 250 KB | 14 | 75.3M | 0.075 ETH | 56.5M | 0.057 ETH | | 400 KB | 23 | 120.5M | 0.121 ETH | 90.3M | 0.090 ETH | | 964 KB | 41 | 288.6M | 0.289 ETH | 218M | 0.218 ETH | For the collection as encoded (99 files, 59.2 MiB): | | gas | @0.5 gwei | @1 gwei | @3 gwei | | pre-encoded | 18.26B | 9.13 ETH | **18.26 ETH** | 54.77 ETH | | raw | 13.70B | 6.85 ETH | **13.70 ETH** | 41.09 ETH | Pointing all 99 tokens afterwards is ~142k gas each — around 0.014 ETH for the lot, a rounding error beside the uploads. Redeeming is paid by the holder: ~130k gas, one transaction. `npm run estimate` prices *your* files rather than these round numbers, by deploying a real `ColorgasmStorage` on a throwaway local chain and measuring each one. Run it before committing to anything — sealing is permanent. npm ci # not `npm install` — see below cp .env.example .env # add ALCHEMY_KEY (or INFURA_KEY) and PRIVATE_KEY npm test # 38 tests, no RPC, no keys Use `npm ci` and keep `package-lock.json`. Every dependency is pinned to an exact version, because gas figures and EDR behaviour move between patch releases and the numbers above were measured against exactly these versions. `npm test` stands up a real Manifold `ERC721Creator` in-process from `fixtures/ERC721Creator.json`, so the extension is exercised against the genuine creator core rather than a mock: wiring, storage, pointers, redeem, batch redeem, all three locks, renderer swapping, and a byte-exact round trip of a multi-chunk image through SSTORE2 → base64 → `tokenURI`. `npm run test:fork` repeats the flow against the real `CLGSM` contract on a mainnet fork, with the real admin and a real current holder. The fixture is frozen bytecode rather than a source dependency on purpose: compiling creator-core from npm drags in OpenZeppelin, and the combination is version-fragile. Dropping it took the install from 873 packages to 128. All of them read addresses from `deployments/<network>.json` (override with `CREATOR=` / `STORAGE=` / `EXTENSION=`) and a token range from `IDS=57,3,12` or | script | what it does | | `deploy.js` | storage + extension + renderer, wired and recorded | | `verify.js` | Etherscan source verification for all three | | `register-extension.js` | `registerExtension` on the creator, from its admin wallet | | `fetch-metadata.js` | builds the per-token metadata fragments from the original Arweave JSON | | `upload.js` | **phase 1a** — one chunk per tx, byte-verified, sealed, resumable | | `point.js` | **phase 1b** — `setArtwork(id, key, metadata)`, one small tx each | | `redeem.js` | **phase 2** — approve + `burnRedeem` / `burnRedeemBatch` | | `inspect.js` | audits keys, seals, bytes and the live `tokenURI` against local files | | `estimate.js` | prices phase 1 per file from a folder of encodes | | `render-ceiling.js` | measures store and render cost across image sizes | | `deploy-creator.js` | a Manifold `ERC721Creator` on a testnet (refuses mainnet) | | `seed-originals.js` | mints Arweave-era stand-ins on a testnet (refuses mainnet) | Two properties worth relying on: - **`upload.js` is resumable and verifies bytes, not sizes.** A key whose stored bytes already match the file is skipped; one that stopped part-way continues from the chunk it reached. Every chunk is read back with `eth_getCode` and compared against the file, so a re-encode that happens to land on the same byte count is never silently accepted. It also waits rather than sending above `MAX_GWEI`, so it is safe to leave running for days. - **The measuring scripts refuse to run on a live chain.** `estimate.js` and `render-ceiling.js` measure by really deploying and really sending, so they check for chainId 31337 first and stop. A live network is only ever read from, for its current gas price. [`RUNBOOK.md`](RUNBOOK.md) is the full procedure — local, Sepolia rehearsal, mainnet, then freezing — including what to do when something goes wrong. Note that `AVIF_DIR` defaults to `../onchain` (the layout of the artist's working folder, where the encoder writes). Point it wherever your encodes live. ## 9. Verifying it yourself None of this asks you to trust the deployment record. For any token: 1. The storage key is the ASCII of `COLORGASM_<id>`, right-padded into a 2. `ColorgasmStorage.chunksOf(key)` returns the SSTORE2 pointer addresses in order, and `isSealed(key)` tells you whether they can ever change. 3. `eth_getCode` on each pointer returns a leading `STOP` byte followed by the raw data. Strip the first byte, concatenate in order — that is the AVIF file. 4. Its SHA-256 should match the line for that piece in [`encode/MANIFEST.sha256`](encode/MANIFEST.sha256). `scripts/inspect.js` does exactly this, and with `DUMP_DIR=dump` writes the images it decoded out of the live `tokenURI` to disk so you can look at them. In increasing order of finality: | action | effect | reversible? | | `storage.append` | writes bytes | no, but harmless — an orphaned blob costs nothing | | `extension.setArtwork` | points a token at a key | yes, until `lockStorage` | | `extension.setRenderer` | changes presentation | yes, until `lockRenderer` | | `renderer.setBase64Json` | JSON wrapper | yes, always (swap the renderer) | | `storage.seal(key)` | freezes a key's bytes | **never** | | `extension.lockStorage()` | freezes every pointer, fragment and the storage address | **never** | | `extension.lockRenderer()` | freezes presentation | **never** | | `burnRedeem` | burns an original | **never** — and it is the holder's call, not the artist's | `lockStorage()` is the guarantee that matters to a collector: the art can no longer change. `lockRenderer()` is deliberately left until much later — it is the only thing that allows fixing presentation, changing the MIME type, or moving to a cheaper renderer. ColorgasmRedeemExtension.sol the Manifold extension ColorgasmStorage.sol SSTORE2 blob storage ColorgasmRendererV3.sol single-pass document assembly interfaces/IColorgasm.sol Manifold + internal interfaces scripts/ deploy, upload, point, redeem, inspect, measure test/ local (28), render (10), mainnet fork (7) fixtures/ERC721Creator.json Manifold creator core, frozen bytecode, tests only deployments/ recorded addresses per network encode_onchain_v2.py PNG → AVIF, constant quality, capped convert.sh AVIF → base64 (pre-encoded storage shape) report.csv per-file sizes and quality metrics MANIFEST.sha256 checksums of the uploaded encodes RUNBOOK.md the full operational procedure `.env` is gitignored and contains only provider keys, a deployer key and an Etherscan key; nothing in this repository needs it to be read. MIT. See [LICENSE](LICENSE). The contracts carry `SPDX-License-Identifier: MIT`. The artworks are not licensed by this repository — the code is MIT, the images