Biscuit

Ethereum smart contracts that generate on-chain metadata

---

What is Biscuit?

Biscuit is a project that generates pseudo mnemonic codes on-chain inspired by BIP39 and turns them into NFTs.

BIP39 describes how to add a checksum to entropy and map it to words from a fixed wordlist (commonly used as 12/24-word phrases).

⚠️ Warning: This project is for entertainment purposes only. Do not use it to generate real wallet mnemonics. The authors assume no responsibility for any losses resulting from use of this repository.

Note: Some SVG previews may render correctly only in Chromium-based browsers.

Quick Start

corepack enable
./start.sh

Manual steps:

pnpm install
pnpm fonts:prepare
pnpm hardhat compile
pnpm hardhat run scripts/render-svg.mjs

Outputs are written to outputs/.

Config

Copy .env.example to .env and fill:

• SEPOLIA_RPC_URL
• SEPOLIA_PRIVATE_KEY (never commit this or use a wallet with real funds)

Hardhat loads .env automatically via dotenv/config.

Architecture

biscuit/
├── .github/          # GitHub configuration
│   └── workflows/    # CI workflows
├── artifacts/        # Hardhat build artifacts
├── assets/           # Fonts, wordlists, and branding assets
│   ├── branding/     # README images
│   ├── fonts/        # Font sources and subsets
│   │   ├── caveat/   # Caveat font files
│   │   └── inter/    # Inter font files
│   └── mnemonic/     # Wordlists for mnemonic generation
├── cache/            # Hardhat compiler cache
├── contracts/        # Solidity contracts and libraries
│   ├── interfaces/   # Contract interfaces
│   ├── libs/         # Shared libraries (rendering, utils)
│   └── test/         # Solidity test harnesses
├── ignition/         # Hardhat Ignition modules
├── scripts/          # Node/Hardhat scripts
├── test/             # TypeScript/Node tests
│   └── integration/  # Integration tests
└── outputs/          # Local outputs (generated SVGs, scratch files)

Sequence

sequenceDiagram
  actor Operator
  actor Client
  participant Fonts as Font prep
  participant Font as BiscuitFont
  participant Mnemonic as Mnemonic
  participant Builder as BiscuitBuilder
  participant Meta as BiscuitMetadata
  participant Renderer as BiscuitRenderer

  Operator->>Fonts: prepare font chunks
  Operator->>Font: deploy and upload chunks
  Operator->>Mnemonic: deploy and set wordlist
  Operator->>Builder: deploy with Font and Mnemonic
  Operator->>Builder: lock Font and Mnemonic

  opt Generate seed optional
    Client->>Builder: generateSeed tokenId
    Builder-->>Client: Seed mnemonicSeed and mnemonicStrength
  end

  Client->>Builder: tokenURI tokenId and seed
  Builder->>Font: letters
  Font-->>Builder: letters bytes
  Builder->>Font: digits
  Font-->>Builder: digits bytes
  Builder->>Mnemonic: generateMnemonic strength and seed
  Mnemonic-->>Builder: words
  Builder->>Meta: tokenURI with SVG params
  Meta->>Renderer: generate SVG
  Renderer-->>Meta: raw SVG
  Meta-->>Builder: base64 JSON data URI
  Builder-->>Client: tokenURI data URI

Loading

License

GPL-3.0 - see LICENSE.