{"componentChunkName":"component---src-templates-blog-post-js","path":"/building-aeons/","result":{"data":{"markdownRemark":{"id":"ed5f05bf-520a-57e1-afaa-9ec6926060f6","html":"

Aeons is an Internet Art Experience on the Base blockchain. With fully onchain art, metadata and gamification, the project can exist without any external pieces. But even with fully onchain ideals, these offchain pieces add greatly to the experience.

\n

This article is a technical description of the code I wrote for Aeons. The first half is the contract suite on Base. It holds the art, the metadata and the rules, and it needs nothing else. The second half is the services that sit outside the chain.

\n

\n \n \n \n \n

\n

16,584 Aeons were minted.

\n

Each token is a fully onchain animation with a limited life. A token starts with four days of life. If the holder does nothing, the token dies and the system burns it. To add life to a token, the holder must merge it with other tokens. That one rule makes a token change its state with time only, and it gives real work to every layer of the stack.

\n

How the project works

\n

The rules of the collection control every technical decision that comes after them. So it is best to know the rules first.

\n

Each token moves through six stages. If a token has more days of life, its stage is higher:

\n

\n \n \n \n \n

\n

The state of the collection is never constant. A smart contract has no scheduler, and it has no idea of “later”. So the primary problem is this: a token must become older and die. The contract can do the former. The offchain services fulfill the latter with a burn call.

\n

The stack

\n

Aeons has four repositories:

\n\n

The contract is the source of truth, and it can run alone. Every other layer watches it and keeps the outside world in agreement with it. None of those layers can change the rules of the game.

\n

\n \n \n \n \n

\n

The mint quantities are examples, but the result is not what you expect. The fee uses the ratio and not the quantity. So the same scarcity effect appears if 5,000 tokens mint or if 40,000 tokens mint. The demand sets the initial size of the collection. The holders set the cost to stay in it.

\n

To see the current data of the collection, use the observatory. It shows how many tokens survive, how many tokens are immortal, and how much life they have.

\n

Death

\n

A token is dead when its clock becomes zero:

\n
function isDead(uint256 tokenId) public view returns (bool) {\n    AeonsStorage.Aeon memory aeon = aeons.all[tokenId];\n    return !aeon.inStasis && aeon.deathTime <= block.timestamp;\n}
\n

A dead token stays in the supply until an account burns it. The contract cannot burn a token by itself when the death time passes, because a contract cannot start a transaction. Some external account must send that transaction. So burnDead is permissionless, and any account can call it on any dead token. If an account burns the token of a different owner, the contract records it:

\n
function burnDead(uint256 tokenId) public {\n    if (!isDead(tokenId)) {\n        revert AeonNotDead();\n    }\n\n    address owner = ownerOf(tokenId);\n    address burner = msg.sender;\n\n    // If called by non-owner of the token, increment total killed\n    if (owner != burner) {\n        aeons.killed += 1;\n    }\n\n    // All calls are token burns, so increment total burned\n    aeons.burned += 1;\n\n    _burn(tokenId);\n\n    emit Death(tokenId, owner, burner);\n}
\n

This makes the removal of dead tokens an open task, and it gives other holders a reason to do it. _beforeTokenTransfers also blocks transfers of dead tokens. So a holder cannot sell a dead token, and an account can only burn it. To call burnDead for thousands of tokens is a task for the offchain services. The section below shows how.

\n

Onchain randomness

\n

The contract assigns the traits (Prism, Energy, Velocity and the colours) with a commit-reveal procedure. This procedure comes from Checks. The random value applies to each epoch, not to each token, and no user can predict it at the mint.

\n

\n \n \n \n \n

\n

Each mint calls resolveEpochIfNecessary(). If the current epoch has no commit, the function selects a block approximately 50 blocks in the future. That block is the source of the random value. When the chain goes past that block, the next mint reveals the value:

\n
} else if (block.number > currentEpoch.revealBlock) {\n    // Epoch has been committed and is within range to be revealed\n    // Set its randomness to the target block hash\n    currentEpoch.randomness = uint128(\n        uint256(\n            keccak256(\n                abi.encodePacked(\n                    blockhash(currentEpoch.revealBlock),\n                    block.prevrandao\n                )\n            )\n        ) % (2 ** 128 - 1)\n    );\n\n    currentEpoch.revealed = true;\n\n    emit CommitReveal.NewEpoch(aeons.epoch, currentEpoch.revealBlock);\n    metadataUpdateAll();\n\n    ++aeons.epoch;\n\n    resolveEpochIfNecessary();\n}
\n

Each token calculates its own seed from the random value of the epoch: keccak256(randomness, tokenId). The contract then compares the seed with fixed cumulative probability tables to select the traits. It writes no data, and it calculates the traits at each read. The rarity of the Energy trait is an example:

\n
/**\n * @dev Get the cumulative probabilities of an energy being selected\n * @return The cumulative probabilities of the energies traits\n */\nfunction energiesProbabilities() public pure returns (uint8[7] memory) {\n    // 1%, 7%, 13%, 15%, 18%, 23%, 23%\n    return [1, 8, 21, 36, 54, 77, 100];\n}
\n

Ivora is the rarest Energy, and it lands 1% of the time. A token is “revealed” when the random value of its epoch is more than zero. Before that time, the token shows a white dormant form.

\n

Fully onchain art

\n

The art is also onchain. tokenURI always assembles the JSON metadata onchain as a base64 data:application/json string. If no external URL is set, AeonsRenderer makes a complete HTML page for the animation. It uses scripty.sol and ethfs to read a gzipped three.js, fflate and the animation script of the project from onchain storage. Then it adds the data of the token.

\n

A static image is the difficult part of a fully onchain project. The contract has a manual onchain SVG fallback for each stage. It also has a dormant form for a token before its epoch reveals:

\n

\n \n \n \n \n

\n

The renderer is behind an interface, and you can replace it (ERC-165 controls this). So you can upgrade or move the art, and you never touch the token contract. The SVG fallback keeps the project complete with no external help. But it is not the real animation. To put the three.js piece on a marketplace card is a job for the offchain services.

\n

Minting

\n

The mint continued for 24 hours, and the demand set the supply. Each token started with the same quantity of life:

\n
// Give every token a starting life time of 4 days from the mint end\naeons.all[tokenId].deathTime = mintEndTime + 4 days;
\n

Each token had four days on the clock from the moment the mint stopped. Then the collection started to become older, and the layers outside the chain started to follow it.

\n

The indexer

\n

The contract knows everything, but it answers one question at a time. A profile page, a status filter and an activity list all need the same thing: the onchain data in a database. The indexer puts it there. It adds nothing to the rules of the game. It makes the collection easy to look at.

\n

The indexer uses Ponder, and it monitors the contract on Base. The procedure is the same for each event: read the full state from the contract, then copy it into Postgres. The Birth handler is an example:

\n
ponder.on(\"Aeons:Birth\", async ({ event, context }) => {\n    const { client } = context;\n\n    const enrichedAeon = await client.readContract({\n        abi: CONTRACT_ABI,\n        address: CONTRACT_ADDRESS,\n        functionName: CONTRACT_ENRICHED_AEON_FUNCTION_NAME,\n        args: [event.args.tokenId],\n    });\n\n    await context.db.insert(aeons).values({\n        id: Number(event.args.tokenId),\n        owner: event.args.minter,\n        deathTime: enrichedAeon.deathTime,\n        stageIndex: enrichedAeon.stageIndex,\n        // ...all traits, colors and status, mirrored from the chain\n        image: `${IMAGE_BASE_URI}${event.args.tokenId}/dead.png`,\n    });\n\n    // ...append to the activity feed\n});
\n

The indexer processes Birth, Collision, Death, Stasis and NewEpoch with the same procedure. The contract stays the source of truth, and Ponder makes it easy to query.

\n

The event model cannot do one thing: the stage of a token changes with time only, and time sends no event. So there is also a block handler. It operates at an interval, and it calculates the ages and the stages again:

\n
blocks: {\n    DailyUpdate: {\n      chain: \"base\",\n      startBlock: Number(startBlock),\n      // 24 hours * 60 minutes * 60 seconds / 2 seconds per block\n      interval: (24 * 60 * 60) / 2, // = 43200 blocks\n    }\n}
\n

A small Hono REST API operates above the database. It has purpose-built endpoints for the tokens of a holder, the activity feed, the dead token ids and the collection stats. The stats endpoint adds the live floor price and the live volume from OpenSea, and it supplies the data for the observatory. Ponder has a GraphQL layer, but a specific JSON API is better here, because the front end can use it directly. This API keeps the profile pages in agreement with the chain.

\n

The offchain services

\n

The listener is the offchain engine of the project. It does two tasks that the chain will not do for itself. The collection is still correct without the listener, but it is much better to use with it.

\n

\n \n \n \n \n

\n

aeons-listener is a Node service. It uses BullMQ with Redis. It monitors the contract with two methods: a getLogs backfill in fixed windows to get the old data, then a watchEvent poll to stay current. Each log that agrees with the filter becomes a job.

\n

A static image of a live animation

\n

Marketplaces need a PNG. An Aeon is a three.js particle animation, and the contract makes it onchain. To connect the two, the service must run the art in a browser and record one frame.

\n

A worker starts Puppeteer and loads the token page. It waits until the animation signals that it is ready, then it records the image:

\n
const html = `<body style=\"margin:0;\">${item}</body>`\nconst dataUrl = `data:text/html;base64;charset=UTF-8,${Buffer.from(html).toString('base64')}`\nawait page.goto(dataUrl)\n\ntry {\n  await page.waitForFunction(\"RENDERED === true\", {\n    timeout: isStage5 ? 15000 : 5000,\n  })\n} catch (e) {}\n\nconst image = await page.screenshot();
\n

The heavy stages need more time to become stable. A Zenith has many particles, thus its timeout is longer. The worker sends the image to Vercel Blob at a fixed path. Then it tells OpenSea to read the image again.

\n

The result: the moment a token collides, dies or becomes immortal, the service makes its image again and sends the update signal to marketplaces automatically.

\n

Burning the dead tokens

\n

burnDead is permissionless, but an account must still call it. The listener does this on a schedule.

\n

Burns go out in batches, behind a distributed lock:

\n
const currentNonce = await publicClient.getTransactionCount({\n    address,\n    blockTag: 'pending',\n});\nlet nextNonce = Number(currentNonce);\n\nfor (const batch of batches) {\n    await walletClient.writeContract({\n        address: AEONS_CONTRACT_ADDRESS,\n        abi,\n        functionName: 'burnDeadMany',\n        args: [batch],\n        account: walletClient.account,\n        nonce: nextNonce,\n    });\n\n    nextNonce++;\n}
\n

Balance checks ensure the service never sends a transaction that would fail.

\n

Bringing it together

\n

Aeons works because each layer has one task, and the boundaries between the layers are clean. The contract owns the art and the rules, and it is the single source of truth. The indexer copies that data into a database and supplies it as an API. The listener monitors the same events and does the two tasks that the chain will not do for itself: it makes an image of the onchain animation for the marketplaces, and it calls burnDead to remove the tokens that are dead. The front end reads the indexer and writes to the contract.

\n

The contract is Aeon’s source of truth. So most of the engineering work is the machinery that keeps the app, the indexer and the marketplaces in agreement with it. That machinery is not the art, and the art does not need it. But it’s what turns the art into a complete experience.

\n

The collection lives here. The observatory shows its state in real time. The contract is verified on Base.

\n

Aeons credits:

\n","excerpt":"Aeons is an Internet Art Experience on the Base blockchain. With fully onchain art, metadata and gamification, the project can exist without any external pieces…","frontmatter":{"title":"Building Aeons: A Full Stack Digital Art Project","date":"10th September 2025","featured_image":{"childImageSharp":{"fluid":{"base64":"data:image/jpeg;base64,/9j/2wBDABALDA4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2P/wgARCAAOABQDASIAAhEBAxEB/8QAFwAAAwEAAAAAAAAAAAAAAAAAAAECBf/EABQBAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhADEAAAAcCkyRB//8QAFxAAAwEAAAAAAAAAAAAAAAAAABEhQf/aAAgBAQABBQLIzHT/xAAUEQEAAAAAAAAAAAAAAAAAAAAQ/9oACAEDAQE/AT//xAAUEQEAAAAAAAAAAAAAAAAAAAAQ/9oACAECAQE/AT//xAAWEAEBAQAAAAAAAAAAAAAAAAAQEQD/2gAIAQEABj8CZqf/xAAcEAACAgIDAAAAAAAAAAAAAAABEQAhEFExQXH/2gAIAQEAAT8hr1CUUgtxx6uXO4Acf//aAAwDAQACAAMAAAAQgM//xAAUEQEAAAAAAAAAAAAAAAAAAAAQ/9oACAEDAQE/ED//xAAUEQEAAAAAAAAAAAAAAAAAAAAQ/9oACAECAQE/ED//xAAaEAEBAQEBAQEAAAAAAAAAAAABEQAhMUGR/9oACAEBAAE/EBoRcWw4BGu5d4ofC+a4iPSd/dTYJOmSt3//2Q==","tracedSVG":"data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20width='400'%20height='270'%3e%3cpath%20d='M0%20135v135h401V0H0v135m183-90c1%201%200%201-2%201h-3l2%201c1%200%202%200%201%201-2%200-1%207%201%207l1%202%201%201c2%200%201%203-1%204-3%201-3%201-5-2-2-2-2-2-2%200l-1%202-2%203c-2%203-2%203%200%203l1-1c0-2%203-2%205-1%203%202%205%204%204%206%200%202%201%201%203-1h2l4%202%203%203%203%202%202%202h2c3-1%206-1%206%201l-4%201-3%201%202%201%204%201%202%201h3l1-1%202-4c1-3%202-4%201-5l-1-5c-1-3-1-3-1-1-1%201-2%202-3%201l-1-2-1-1v-1l2-1-2-1v-1l2-3%202-1h1v-2l1%201%201%201%201-1%201-2c4-2%204-10%200-9l-3-1c-2-2-6-3-8-2-2%203-6%202-6%200h-2l-3%203c-2%200-2%200%200%201%201%201%201%201-1%201s-3-1-3-3c0-3-2-4-2-1l-1%205-1-1-1-1c-1%200-2-1-1-3l-1-3c-2%200-2%201-2%202m-6%20114l1%204%202%203h-3c-3%200-3%204%201%208%202%203%203%203%206%203%204-1%207%201%206%203v2c1%202%201%202%202%201%202-2%202-2%204%200l2%205%2010%202h9l-4-3-4-3-4-2-3-1v-11c1-11%200-12-3-10-2%201-3%203%200%203l-1%202c-2%202-2%202-3%201l-3-1-3-2-4-3-1-1h-7m-93%207l-7%207c-2%204-3%209-1%209l1-4%201-3c1%201%202%200%203-2%201-4%2010-9%2010-6l-4%205c-4%203-4%204-5%2010v7c2%201%200%203-2%202-2%200-2%200-1%202%202%204%2012%208%2015%207%201%200%201-4-1-5-1-1%200-1%203-1%203%201%204%201%204-1l2-3v-6c0-2%200-2%201%201l1%203%201-3v-6l-2-4-4-4c-5-3-6-5-4-5l1-1c-2-2-8-1-12%201m215%203l-2%203-2%202-2%202%206-3c1-3%205-2%206%200v2l2%201c2%200%203%201%203%204l-1%205-1%203-2%204v4l1%202c-1%201%202%204%203%203%201%200%202-1%201-2%200-3%200-3%202-2%202%200%202%200%201-1l-2-1-1-2%201-2c1%201%203-4%202-6v-5c1-7%201-9-1-10l-4-1c-5-2-8-2-10%200m-28%2019c-3%204-4%204-3%209%200%203%201%206%203%208l3%203v-2l1-5%201-4c1-1%201-1-1-1h-3l4-6c5-6%201-7-5-2'%20fill='%23d3d3d3'%20fill-rule='evenodd'/%3e%3c/svg%3e","aspectRatio":1.4792418772563176,"src":"/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/bc3a8/aeons-gallery.jpg","srcSet":"/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/d278e/aeons-gallery.jpg 200w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/8539d/aeons-gallery.jpg 400w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/bc3a8/aeons-gallery.jpg 800w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/81ef8/aeons-gallery.jpg 1200w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/989b1/aeons-gallery.jpg 1600w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/68945/aeons-gallery.jpg 1639w","srcWebp":"/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/c6096/aeons-gallery.webp","srcSetWebp":"/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/1932c/aeons-gallery.webp 200w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/f4957/aeons-gallery.webp 400w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/c6096/aeons-gallery.webp 800w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/b6424/aeons-gallery.webp 1200w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/7a72d/aeons-gallery.webp 1600w,\n/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/fd5c5/aeons-gallery.webp 1639w","sizes":"(max-width: 800px) 100vw, 800px","originalImg":"/static/a6b3bfd7e29dc69b701e1d6e44b31a9b/68945/aeons-gallery.jpg","originalName":"aeons-gallery.jpg","presentationWidth":800,"presentationHeight":541}}},"url":"/building-aeons/","categories":["Programming","web3","Crypto","Software Engineering","NFTs"],"tags":["Solidity","TypeScript","Next.js","Base","Ethereum","Ponder","NFTs","Onchain Art","Full Stack"],"hide_featured_image":true,"mentorship_og_image":null,"custom_excerpt":"How to build a full stack onchain art project on Base. This article shows the smart contract suite, the blockchain indexer and other services that add to the experience."}}},"pageContext":{"slug":"/building-aeons/","previous":{"fields":{"slug":"/2024-a-year-in-review/"},"frontmatter":{"title":"2024 - A Year In Review"}},"next":{"fields":{"slug":"/2025-a-year-in-review/"},"frontmatter":{"title":"2025 - A Year In Review"}}}},"staticQueryHashes":["1331100284","1975953531","3493025416"]}