Overview

Fully onchain 40x40 pixel art PFPs on Ethereum.

Ethereans are fully onchain 40x40 pixel art PFPs on Ethereum. Each Etherean is linked to an X (Twitter) handle and comes with its own ERC-6551 Token Bound Account (TBA), a smart contract wallet owned by the NFT itself.

Key Properties

• >
  Fully onchain SVG: no IPFS, no external dependencies. The pixel data is stored directly in the contract and rendered as SVG at tokenURI time.
• >
  4-color palette system: 8 named palettes inspired by the Game Boy color space (classic, pink, ocean, amber, grayscale, lavender, crimson, mint).
• >
  Gasless minting: users never connect a wallet. A protocol relayer pays gas, funded by the $ADHD treasury.
• >
  ERC-6551 TBA: every token gets a deterministic Token Bound Account created atomically during mint.
• >
  One per handle: each X handle can only mint once (enforced onchain via case-insensitive hash). X user IDs are stored onchain for post-mint analytics and potential airdrop blacklisting.

Current Status

Architecture

End-to-end system design: browser to blockchain.

System Diagram

Key Design Decisions

• No wallet connection required. Users provide a receive address manually.
• EIP-712 typed data signatures bind the verifier attestation to the exact mint parameters (handle, to, svgData, palette, nonce, expiry).
• Separate relayer and verifier keys. The relayer is a funded EOA that submits transactions. The verifier is a separate EOA that signs attestations. These are different keys for security.
• ENS resolution happens client-side via the ensdata.net public API.

Smart Contract

Etherean.sol and SVGRenderer.sol on Ethereum.

Etherean.sol

Constructor Parameters

Mint Function

function mint(
    address to,
    string calldata handle,
    bytes calldata svgData,
    string calldata palette,
    bytes32 nonce,
    uint256 expiry,
    bytes calldata signature
) external onlyRelayer returns (uint256 tokenId, address tba)

Mint Flow (7 Steps)

1. Check expiry timestamp
2. Check and consume nonce (prevents replay)
3. Derive case-insensitive handle hash
4. Enforce handle uniqueness
5. Verify EIP-712 signature against verifier
6. Validate svgData is exactly 400 bytes
7. Mint ERC-721 token, store data, create ERC-6551 TBA

EIP-712 Domain

name: "Etherean"
version: "1"
chainId: (current chain)
verifyingContract: (contract address)

EIP-712 Mint Type

Mint(string handle, address to, bytes svgData, string palette, bytes32 nonce, uint256 expiry)

View Functions

Admin Functions (onlyOwner)

• setRelayer(address): update the relayer address
• setVerifier(address): update the verifier address
• transferOwnership(address): transfer contract ownership (inherited from OpenZeppelin Ownable). Recommended: transfer to a hardware wallet before mainnet.

Custom Errors

HandleAlreadyMinted InvalidSignature ExpiredSignature NonceAlreadyUsed InvalidSVGData OnlyRelayer ZeroAddress

SVGRenderer.sol

A pure library that:

• Unpacks 400 bytes of 2-bit packed pixel data (1,600 pixels total)
• Resolves palette colors from a string key (8 palettes hardcoded)
• Renders a complete SVG document with 1,600 rect elements
• Uses assembly-backed buffer writes for gas efficiency

Bit Layout

Pixel index i is in byte i/4, at bit-offset (3 - (i % 4)) * 2 (MSB first).

Token Metadata Format

The tokenURI returns a base64-encoded JSON object:

{
  "name": "Etherean #1",
  "description": "Fully onchain 40x40 pixel PFP on Ethereum. @handle",
  "image": "data:image/svg+xml;base64,...",
  "attributes": [
    { "trait_type": "Handle", "value": "gami_vc" },
    { "trait_type": "Palette", "value": "classic" }
  ]
}

API

Cloudflare Worker endpoints for verification and minting.

POST /api/verify

Searches X for a verification tweet containing the nonce. The user's tweet must contain all three of: the nonce string, the word "Etherean", and "@gami_vc".

Request

{
  "handle": "gami_vc",
  "nonce": "A7K2F9"
}

Response (success)

{
  "verified": true,
  "handle": "gami_vc",
  "nonce": "A7K2F9",
  "expiry": 1709312400,
  "verifyProof": "...",
  "message": "Verified! Ready to mint."
}

Response (failure)

{
  "verified": false,
  "message": "Tweet not found. Please post the tweet and try again."
}

Rate-limited per IP. Returns 429 with Retry-After header if exceeded.

POST /api/mint

Validates the attestation and submits the mint transaction to the blockchain.

Request

{
  "handle": "gami_vc",
  "to": "0x1234...abcd",
  "svgData": "0x...",
  "palette": "classic",
  "expiry": 1709312400,
  "nonce": "A7K2F9"
}

Response (success)

{
  "success": true,
  "tokenId": 42,
  "txHash": "0xdef...",
  "tba": "0x789...",
  "etherscanUrl": "https://etherscan.io/tx/0xdef..."
}

Attestation expiry: mint must be completed within a short time window after verification.

GET /health

{ "status": "ok", "service": "ethereans-api" }

Frontend

Client-side application hosted on Cloudflare Pages.

Overview

The frontend is a static site with no build step, served via Cloudflare Pages. It handles image generation, palette selection, Twitter verification, and the mint flow.

Pixel Art Pipeline

1. Load image (via unavatar.io for X PFPs, DiceBear fallback, or file upload)
2. Downsample to 40x40 with bilinear interpolation (center crop to square)
3. Convert to grayscale using ITU-R BT.601 luminance
4. Quantize to 4 levels using threshold quantization (dithering disabled by default)
5. Render to canvas at display scale (8x) and generate SVG string

2bpp Packing

Packs 1,600 palette indices (each 0-3) into 400 bytes. Bit layout per byte (MSB first):

[ px0 | px1 | px2 | px3 ]
 7-6   5-4   3-2   1-0

Output: "0x" + 800 hex digits = 802 chars total.

ENS Resolution

Uses the ensdata.net public API. If the wallet input matches an ENS pattern (word.tld), resolves to a 0x address before submitting the mint request. Shows "Resolving ENS..." spinner during resolution.

Mint Flow

1. User enters X handle, generates pixel art preview
2. User selects palette and enters receive address (0x or ENS)
3. Verification section appears: user posts a tweet containing a 6-char nonce
4. User clicks "I've Posted It", frontend calls POST /api/verify
5. On success, mint button enables. User clicks "Mint to Ethereum"
6. Frontend packs pixel data, calls POST /api/mint
7. Progress steps animate: Encoding SVG, Packing data, Minting, Creating TBA, Done
8. Result shows tx hash with Etherscan link

Palettes

8 named palettes, each with 4 colors from darkest to lightest. Hardcoded in both the frontend (engine.js) and the contract (SVGRenderer.sol).

Full Reference Table

Deployed Addresses

Contract addresses and service URLs across networks.

Sepolia Testnet Current

Mainnet Planned

Mainnet Checklist

Items required before mainnet deployment.

1. 01

   Smart contract audit In Progress

   External audit currently reviewing smart contract, backend, and frontend.

2. 02

   Contract verification on Etherscan Pending

   Verify contract source code on Etherscan for transparency.

3. 03

   Mainnet deployment Pending

   Deploy contracts to Ethereum mainnet after audit completion.

Security Considerations

Threat model and mitigation strategies.

• Immutable contract: no proxy, no upgradeability. If a critical bug is found, a new contract must be deployed.
• Permissioned minting: only the relayer can call mint(), and every mint requires an EIP-712 signature from the verifier.
• Separate keys: relayer and verifier use different EOAs. Compromise of one alone cannot mint.
• Nonce replay protection: each nonce can only be used once (mapping in contract).
• Expiry window: attestations expire within a short time window.
• Handle uniqueness: enforced onchain via keccak256 of lowercased handle.
• Rate limiting: API endpoints are rate-limited per IP.
• No wallet connection: users never expose their private keys to the frontend. They provide a receive address only.

Repository

Source code structure and organization.

High-Level Structure

The project is organized into three main areas:

• Frontend: static HTML, CSS, and JavaScript served via Cloudflare Pages.
• API: Cloudflare Worker handling verification and minting.
• Contracts: Solidity smart contracts built with Foundry.

Source Code

The repository is private. See GitHub for the latest changes.

Cartridges

Tiny onchain games that distribute tokens through human coordination.

What to Expect

Each cartridge will have its own documentation covering:

• Game mechanics and rules
• Token details (if applicable), distribution method, treasury
• Smart contract addresses
• How to play

First Cartridge: Game of $GNAR

Gnars Numerical Assessment of Radness by the Global Network for Attested Reality Systems. An incentive to create verified media at scale, rewarding people who consistently prove they're real and add culture.