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",
  "tweetId": "1234567890",
  "expiry": 1709312400,
  "message": "Verified! Ready to mint."
}

Response (failure)

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

Rate limiting: 10 requests per IP per minute. Returns 429 with Retry-After header.

POST /api/mint

Validates the attestation, signs the EIP-712 message with the real mint parameters, and submits the transaction via the relayer.

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: 30 minutes. The mint handler rejects attestations expiring in fewer than 30 seconds.

GET /health

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

Worker Project Structure

Environment Variables

wrangler.toml (non-secret)

Secrets (via wrangler secret put)

Frontend

Client-side application hosted on Cloudflare Pages.

File Structure

Pixel Art Pipeline (engine.js)

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 (packer.js)

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 (app.js)

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.

The First 100 Gallery (ogs.js)

Displays the first 100 minted Ethereans in a 10-column grid. Fetches data directly from the contract via JSON-RPC batch requests to Alchemy. Uses caching: token data is immutable onchain, so cached entries never need invalidation. Only totalSupply() is fetched on every load to check for new mints.

Mint Flow (app.js)

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

   Add TBA address to tokenURI metadata Planned

   Compute dynamically via registry account() view function. Include as an attribute: {"trait_type": "TBA", "value": "0x..."}

2. 02

   X user ID storage Planned

   Store X user ID onchain (as bytes32 hash) alongside each mint. This does not block duplicate mints from the same account after a handle change. Instead, the data is used post-mint to identify accounts with multiple Ethereans (via different handles) and blacklist their TBAs from future airdrops or mints if needed.

3. 03

   Smart contract audit In Progress

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

4. 04

   Contract verification on Etherscan Pending

   Sepolia contract not yet verified. Must verify before mainnet.

5. 05

   CORS hardening Pending

   Tighten API CORS from * to https://console.gami.vc.

6. 06

   Transfer ownership to hardware wallet Pending

   Call transferOwnership() to transfer contract ownership from the deployer EOA to a hardware wallet (e.g. gami.eth). Protects admin functions (setRelayer, setVerifier) from deployer key compromise.

7. 07

   Mainnet deployment Pending

   Deploy contracts to Ethereum mainnet. Update wrangler.toml with mainnet chain ID and contract address. Fund relayer EOA with ETH. Update frontend RPC URL and contract address.

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 the relayer key alone cannot mint (needs verifier signature). Compromise of the verifier key alone cannot mint (needs relayer to submit tx).
• Nonce replay protection: each nonce can only be used once (mapping in contract).
• Expiry window: attestations expire in 30 minutes.
• Handle uniqueness: enforced onchain via keccak256 of lowercased handle. A user can change their X handle and mint again. X user IDs are stored onchain so these cases can be identified and blacklisted from airdrops or future mints.
• Rate limiting: API rate-limits verify requests to 10/min per IP. In-memory limiter resets per isolate cold start. KV-backed limiter available for stricter enforcement.
• CORS: currently set to * (to be tightened to console.gami.vc for mainnet).
• Relayer EOA: holds real ETH. Private key stored in Cloudflare Worker secrets only.
• No wallet connection: users never expose their private keys to the frontend. They provide a receive address only.

Repository

Source code structure and organization.

Directory Structure

Latest Commit

5096830e: client-side caching for gallery