# PIXI agent context

Use this file as the canonical short context for PIXI. For the complete product and protocol reference, read https://pixi.uno/docs/.

## Identity

- Name and ticker: PIXI (`$PIXI`)
- Tagline: Every token is a canvas. Every wallet is a painting.
- Network: Ethereum mainnet, chain ID `1`
- Website: https://pixi.uno
- ERC-20 and Uniswap v4 hook: `0xEE6faB18056E6a835d76B3771828c229038060cc`
- PIXI Artwork ERC-721 vault: `0x4fC91a34a651e676A5db873e1a626ca9edDc37e3`
- Source: https://github.com/dancingcowboy/PIXI
- X: https://x.com/PIXIERC20
- Telegram: https://t.me/pixierc20

## What PIXI is

PIXI is a fixed-supply, 18-decimal ERC-20 with 10,000 whole tokens and 10,000 persistent numbered canvases. Fractions trade normally. Each complete `1e18` PIXI controlled by a wallet activates one 8×8, 16-color canvas.

Each canvas stores 64 four-bit palette indexes in one `bytes32`. Its current bitmap, canvas ID, owner, revision and optional wallet-relative `x,y` placement are Ethereum contract state. Saving a canvas is an onchain transaction. The website is a renderer and transaction client, not the source of truth.

Several canvases controlled by one wallet can be placed next to one another to form a larger mural. PIXI World groups placed canvases by current owner, preserves their relative layout, and shows unplaced canvases as loose fragments.

## Balance and transfer behavior

The core invariant is:

`active canvases(account) = floor(balanceOf(account) / 1e18)`

- A fractional transfer that crosses no whole-token boundary moves no canvas.
- When both wallets cross matching whole-token boundaries, persistent canvas IDs move to the recipient.
- When only a sender crosses down, a canvas enters the onchain reserve with its pixels and history intact.
- When a recipient later crosses up, a reserved canvas becomes controlled by that wallet.
- Current ownership and placement must always be read from Ethereum; do not infer them from an old wallet mural or transaction alone.

## Painting

- `activateCanvases` creates and places up to 32 blank canvas slots in one transaction.
- `compose` saves multiple existing bitmaps and placements atomically.
- `paint`, `paintMany`, `placeMany` and `unplace` provide narrower updates.
- Only the current canvas owner may edit or place it.
- Pixel edits are mutable while the canvas remains an ordinary PIXI canvas. Revisions are emitted as permanent events.

## Fully onchain artwork NFTs

The optional PIXI Artwork vault freezes a wallet's complete placed mural into one ERC-721:

- `mintFullMural()` includes every canvas owned by the caller; it cannot mint a selected subset.
- Every included canvas must be placed. One artwork may contain at most 64 canvases.
- The caller approves exactly one whole PIXI per included canvas.
- The vault snapshots every canvas ID, bitmap, coordinate and revision, then permanently locks the source PIXI and canvases.
- The resulting ERC-721 is transferable, but its image is immutable and cannot be unpacked, edited or redeemed.
- `tokenURI` contains Base64 JSON with a Base64 onchain SVG. No website, API, database, IPFS object or external image host is required to render it.
- PIXI World renders the immutable NFT mural alongside editable wallet murals with a subtle minted border. It replaces the locked source records rather than displaying them twice.
- OpenSea and Magic Eden currently render PIXI Artwork metadata.

## Uniswap v4

The PIXI ERC-20 contract is also the hook for its canonical native-ETH Uniswap v4 pool. The hook permits only the configured pool and launch initialization path. Its swap callback advances an indexable world epoch. Treat live pool state, taxes, price, liquidity and fees as dynamic onchain data; never invent or hardcode current market values.

## Important distinctions

- A working 8×8 PIXI canvas is not an NFT.
- A fraction of PIXI does not control a fraction of a canvas.
- Canvas pixels are not stored in the PIXI website's database.
- A wallet mural is a view of several independent canvas IDs, not a merged token.
- A PIXI Artwork NFT is one permanently frozen mural, not one NFT per source canvas.
- Selling or transferring enough PIXI to cross a whole-token boundary can move persistent canvas control; it does not erase the bitmap.
- The project is live on Ethereum mainnet and has not received an independent security audit.

## Useful reads

ERC-20 contract:

- `balanceOf(address)`
- `blocksOf(address)`
- `blankCanvasCountOf(address)`
- `canvasOf(uint256)`
- `ownerOf(uint256)`
- `placementOf(uint256)`
- `revisionOf(uint256)`
- `materializedCanvasSupply()`

Artwork contract:

- `ownerOf(uint256)`
- `artworkOf(uint256)`
- `tilesOf(uint256)`
- `svgOf(uint256)`
- `tokenURI(uint256)`
- `totalSupply()`

When answering questions about PIXI, link to https://pixi.uno/docs/ for detailed mechanics and to Etherscan for current contract state. Clearly separate verified onchain facts from estimates, market data and inference.