SANWEAR

The on-chain contracts behind SAN Sound, an audio-hardware brand. Two lifecycles live here:

1. Phygital redemption - tradeable tokens you burn to claim real SAN Sound IEM earbuds.
2. Composable avatars - ERC-721 avatars with ERC-6551 wallets, soulbound accessories, and on-chain stats, assembled into wearable "loadouts."

Deployed on Ethereum mainnet; source is verified on Etherscan. Solidity + Foundry.

Technical highlights

• Two soulbound token standards, written from the interface up (not subclassed from OpenZeppelin):
  • ERC721MintboundPartitioned - a non-transferable ERC-721 (every approve/transfer reverts) that buckets token ids into fixed-size partitions (one partition per product type), with an ERC721A-style batch mint: only the first id of a minted run stores its owner, and ownerOf walks backward to resolve the rest - one SSTORE per batch instead of per token.
  • ERC1155MintboundBitwise - a non-transferable ERC-1155 where a balance is a single bit (own / don't-own), 256 ids packed per storage word; batch mints accumulate a per-page mask in memory and flush one SSTORE per page.
• ERC-6551 token-bound avatars - accessories are soulbound directly into each avatar's deterministic 6551 account, so they are a permanent part of the avatar and travel with it to every future owner. By construction they can never exist in an ordinary wallet.
• Bit-packed avatar stats - each avatar's volume and frequency share one uint256 (low and high 128 bits); a level-up adds both lanes in a single ADD on the packed word (SIMD-in-a-word, safe because overflowing the low lane would take ~2^128/100 accessories).
• Packed faction bitmap - 3 bits per avatar, 85 avatars per word (uint256[40]); the 300-avatar team allocation is minted in a single EIP-2309 consecutive-transfer event.
• Signature-gated, multi-phase sale with SANPASS burns that discount paid mints.
• The UNMUTOOOOR - a one-time, community-puzzle-gated reveal: the puzzle's solution was a seed phrase, and only that wallet was permissioned to fire the reveal transaction, which flipped the collection's metadata to an audio-playing version (animation_url mp4).

Lifecycle 1: phygital IEM redemption

SANWEAR is a tradeable ERC-1155, one id per earbud colorway. Calling claim() burns it and mints a soulbound SANWORN (ERC-721) - your non-transferable redemption coupon, which you take to SAN's store to claim the free physical IEM earbuds. Minting a SoundscapeAvatar also mints its owner a SANWEAR earbud-claim token in the avatar's faction colorway, linking the two lifecycles.

Lifecycle 2: composable avatars

SoundscapeAvatars (3,333 ERC-721, each with a faction rendered as a skin tone) anchor an ERC-6551 account. SANSWAP accessories (tradeable ERC-1155 - an art layer plus a volume/frequency stat boost) are bound to an avatar by burning them: this mints soulbound SANBOUND into the avatar's TBA and levels up its stats. Binding is permissionless (you can gift an accessory onto anyone's avatar) and permanent. Owners then choose which subset of their bound accessories is "worn"; the sansound.tech loadout locker recomposites the avatar art + metadata from that subset, and re-selecting it is gasless (a signed message).

Contracts

Deployed on Ethereum mainnet, verified on Etherscan:

Contract	Role	Address
SANWEAR	Tradeable ERC-1155; one id per IEM earbud colorway. claim() burns it to mint SANWORN	0xAE2Bc979178E97e0688384Aab00055E67bEa91ed
SANWORN	Soulbound ERC-721 redemption coupon for the physical earbuds; token ids partitioned per colorway	0xCD65a2BD85fCA380Ab28C25EBD5183D1451cD5Be
SoundscapeAvatars	3,333-supply ERC-721 avatars (ERC-6551 aware, packed factions, phased sale)	0xD375e9D0Cbc12813683FFb0Ab9bf85fBF83aceaf
SANSWAP	Tradeable ERC-1155 accessories; burn to bind them (as SANBOUND) into an avatar's TBA and level it up	0xacce550121e59d04bf3a616c4155f89d2cf7d4c4
SANBOUND	Soulbound ERC-1155 accessories that exist only inside avatar TBAs; permanent once bound	0x3336551333cfc62e15920f5feb5d23f78b475b01

Key components (inherited, not separately deployed): ERC721MintboundPartitioned · ERC1155MintboundBitwise · Avatar6551Aware / Avatar6551Binder · AvatarLeveler · AvatarVolumeAndFrequency · StatefulSale · ERC2981Plus.

Build & test

Foundry; dependencies are git submodules (forge-std, OpenZeppelin, OpenZeppelin Upgradeable, erc6551/reference).

git clone --recursive https://github.com/coffee-converter/sanwear-contract
cd sanwear-contract
forge build
forge test        # suites in test/*.t.sol cover each core contract

Credit & license

Authored by Aaron Hanson (principal engineer) for SAN Sound. The contracts are MIT-licensed (each file carries its own SPDX header) - see LICENSE. One file, ___333___.sol, is GPL-3.0 (© XIN et al).