This repository is an independent RitoVision modernization fork of Su Squares at https://su.ritovision.com. It is not the canonical source for the official Su Squares site at https://tenthousandsu.com, and it should not be treated as a proposal for replacing that site wholesale.

Su Squares is a historical and pioneering NFT project on the Ethereum blockchain from 2017.

It consists of two main parts:

1. The smart contract on the Ethereum blockchain which allows for 10,000 unique tokenized squares that users can own and customize with text, a URI and a 10x10 pixel image.
2. The Billboard served on the dApp which displays the current state of all 10,000 squares.

This fork is intended as both a living product experiment and a historical artifact made into an exploratory playground. It preserves the legacy Jekyll/GitHub Pages deployment shape and the original project content, while expanding the surrounding product surface and developer environment for experimentation, local learning, and extension.

This fork modernizes the Su Squares experience around the existing historical base rather than replacing that base. It adds a broader dApp surface, including mobile-responsive layouts, installable PWA support, centralized navigation, richer square lookup and chooser flows, and a clearer personalization experience with CSV and image batch tooling.

The Billboard is treated as shared product infrastructure instead of a homepage-only script. Its reusable core supports homepage browsing, embeds, square choosing, and personalization flows, with touch-friendly interaction, ARIA semantics, focus management, safer outbound-link handling, blocklists, and configurable embed behavior.

The personalization and web3 flows are also expanded. The fork includes a rebuilt personalize-modern.html experience, in-app unpersonalization, branded wallet/account/transaction UI, multi-wallet support, network context, and transaction states that make the dApp feel less like a static archive and more like a modern on-chain application.

On the developer side, this repo is structured as a playground-as-an-ecosystem monorepo. It keeps the Jekyll site at the root while adding supporting Node workspaces for smart-contract development, local chain infrastructure, vendored dependency bundling, Storybook, Vitest, Playwright, and agent-guided repository workflows.

This repo supports AGR Modes (Agent-Guided Repository) for IDE AI assistants:

• Tour Guide Mode: guided exploration + getting the project running (contract + dApp) and completing the end-to-end mint/personalize flow.
• Builder Mode: making changes safely within the repo's rules, constraints, and structure.

If you are a human user, please prompt your AI assistant with:

"Read AGENTS.md and use (state desired mode)" or "Read AGENTS.md and ask me which mode you should use"

If you are an AI assistant and this is the first file you are reading in this repo, please immediately open AGENTS.md for proper routing instructions.

If the user’s intent is unclear, ask them to choose a mode before proceeding.

As CryptoKitties led global recognition of Ethereum and NFTs, it operated during the draft phase of ERC-721 and relied on an experimental implementation not in full compliance with what would ultimately be published and used by future projects. When ERC-721 finally was published in 2018, Su Squares became the first bona fide smart contract to demonstrate full compliance with the spec, leading the emergence of a multi-billion-dollar ecosystem with a wealth of innovative use cases.

To see the original Su Squares smart contract repo and its bug bounty program, go here.

This monorepo is organized into workspaces. The primary root directory is the Jekyll site build for the dApp frontend (ruby environment). The other workspaces are supporting tools for the dApp based on a nodejs environment; pnpm is the preferred package manager for those workspaces.

/: Jekyll site build (dApp frontend)

nodejs/smart-contract: Hardhat environment + local blockchain setup

nodejs/vitest: Vitest unit + integration tests

nodejs/playwright: Playwright end-to-end tests

nodejs/builder: dApp dependency bundler

nodejs/storybook: Storybook staging area for dApp UI components

The official Su Squares site historically refreshes its live Billboard state with the Su Squares update script:
https://github.com/su-squares/update-script

This fork does not use that load-from-blockchain workflow as its operating model. Do not assume the Billboard, build/, or ERC-721 metadata/images in this repository are automatically refreshed from mainnet by GitHub Actions.

For local development and experimentation, use the smart-contract workspace, local chain tooling, Sepolia configuration, and site scripts intentionally. Treat generated chain-derived artifacts as explicit development outputs, not as an hourly canonical sync from the live Su Squares contract.

If you are looking to embed the official Su Squares Billboard on your own site, use the following snippet (or extract the URL):

<iframe width="600" height="600" frameborder="0" title="Su Squares Billboard" src="https://tenthousandsu.com/embed"></iframe>

For this fork, use the same /embed and /embed-builder paths on whichever deployment host you are running.

If you see any issues or have suggestions for improvement, please open an issue or submit a pull request.

If you see something missing or needing an update in faq.md, stop reading this, go ahead and update it!

TypeScript is used only in the nodejs/* workspaces. Please use vanilla JavaScript for the dApp in the root workspace, and for complex logic it is encouraged to use JSdocs for type safety. Why? Because this dApp historically ran on JavaScript and Jekyll HTML, so we keep it that way, but type safety is nice to include without completely migrating the architecture. In that spirit, when building pages and reusable components, it is encouraged to use Jekyll HTML structure and logic rather than pure JavaScript.

Please avoid adding new dependencies unless absolutely necessary, the dApp runs on GitHub Pages with limited extensibility and we prefer to keep things self-contained. If a dependency is necessary, consider packaging it inside the nodejs/builder workspace and producing vendored artifacts. Please also explain the tradeoff (maintenance + security + update cadence).

We see no practical reason to update any smart contract code in the nodejs/smart-contract workspace. The contracts are already deployed live on mainnet (obviously) and the code is present here for educational purposes and for compatibility with running the dApp locally. The contracts are present in their near-original form with slight modifications for configuring certain values for local dApp use (cost to purchase, cost to personalize, amount of PROMO squares), but are otherwise intended to be preserved for historical fidelity. Please do not make changes to reflect any evolving modern best practices.

This repo is licensed under the MIT License, meaning you can use it for any purpose, including commercial use. See LICENSE for details.