How UniAudio generates music + image

1. Token + hook (ERC-404 lite)

Two contracts: AudioToken (ERC-20 with per-whole-unituAUD NFTs) and AudioHook (V4 hook + on-chain SVG generator). Modeled on the Unipeg / UpegHook reference deployed on Ethereum mainnet — uAUD is our renamed branding of that pattern.⟨src⟩ contracts/src/AudioToken.sol :: contract AudioToken⟨src⟩ contracts/src/AudioHook.sol :: contract AudioHook

swap on AUDIO/X pool ─► PoolManager ─► AudioHook.afterSwap
                                          │
                                          └─ randomSeed = keccak(seedTicks, prev,
                                                                blockhash, prevrandao,
                                                                block.number, timestamp,
                                                                sender, amountSpecified,
                                                                delta0, delta1,
                                                                tick, sqrtPriceX96)

router → buyer ERC-20 transfer
   │
   └─► AudioToken._update
         │   if balanceAfter / 1e18 > balanceBefore / 1e18:
         │       hookSeed = AudioHook.randomSeed()
         │       seed     = keccak(hookSeed, upegId, buyer, block.number)
         │       mint uAUD #N to buyer
         │   symmetric burn on outflow
         ▼
   AudioToken.tokenURI(N) → JSON { image: SVG, attributes: [seed] }

• 1 whole uAUD token ↔ 1 uAUD NFT. Crossing a 1 ether boundary on transfer mints/burns.⟨src⟩ contracts/src/AudioToken.sol:171-197 :: _update⟨src⟩ contracts/src/AudioToken.sol:30 :: UNITS = 1 ether
• Excluded addresses (PoolManager, hook, routers, treasury) skip the auto mint loop — gas-bomb otherwise.⟨src⟩ contracts/src/AudioToken.sol:65-70 :: constructor exclusions⟨src⟩ contracts/src/AudioToken.sol:98-106 :: setUAUDExcluded
• Hook permission flags: AFTER_ADD_LIQUIDITY | AFTER_SWAP = 0x440. Address mined via CREATE2.⟨src⟩ contracts/src/AudioHook.sol:72-89 :: getHookPermissions
• transferUAUD(to, id) moves 1e18 + a specific uAUD NFT id atomically.⟨src⟩ contracts/src/AudioToken.sol:152-165 :: transferUAUD
• The hook IS the SVG generator (10 layer slots, 36-color palette, 24×24 canvas) — single contract, no separate image module.⟨src⟩ contracts/src/AudioHook.sol:32 :: contract AudioHook is BaseHook, SvgGenerator, ...

2. One seed, two consumers

The 256-bit seed feeds two non-overlapping decoders — they share entropy but never alias.

Do not change either decoder post-launch — existing seeds would render different art / play different music. The on-chain decoder is frozen by deployment; the off-chain decoder is frozen by audit (TS port mirrors Solidity byte-for-byte).⟨src⟩ web/src/lib/engine/audioMetadata.ts :: decodeAudioMetadata (TS port)

3. Constrained random — music engine

Pure note-by-note randomness sounds like noise. The trick is that each decision layer can only pick from a table the music theory has already vouched for. The deeper you go (down to individual notes and drum hits), the tighter the constraints get.

Genre → Key+Mode → Tempo+Form → Progression → Bass → Melody → Drums → Timbre → FX
 (broad)                                                                          (narrow)

Every layer eats a few bits of the 256-bit seed. Genre is decided first, then it gates everything below — e.g. Lo-fi cannot use the Lydian mode and cannot land on 130 BPM.

4. Music engine bitfield (bits 0..81) — off-chain

parseGenome(hex) slices the low 82 bits of the seed into named fields:

5. The 8 inviolable laws

This rule set is what keeps the output from collapsing into noise. Each law has a concrete music-theory reason behind it.

1. Genre gates every layer below — genre is decided first; mode, BPM, drums, patches, and progression all filter through it
2. Every note lives in the scale — chromatic passing tones are allowed only on the weak 16th-note slots
3. Downbeat = chord tone — slot 0 (beat 1) and slot 8 (beat 3) MUST be the root/3rd/5th of the chord — anti-atonal anchor
4. Progressions come from a hardcoded palette — I-V-vi-IV, ii-V-I, Andalusian… chords are never picked at random
5. Voice leading ≤ 2 semitones — pad voicing in close root position; common tones held between chords
6. Cadence rule — last note of bar 8 → chord root; last note of bar 16 → tonic. Phrases must close
7. Motif loop + variation — one rhythmic pattern persists through the section; melody is never built from scratch every bar
8. Patches & drum patterns are tuned presets — 32 lead/pad/bass patches, 5 drum patterns — synth params are never randomized

6. Per-layer details

Genre (4 bit)

Four genres ship today: Lo-fi Hip Hop · House · Ambient · Synthwave. Each genre is a schema that gates everything below it — BPM range, allowed modes, drum kit, synth patches, progression palette.

Mode (3 bit)

Eight 7-note modes: Ionian, Dorian, Phrygian, Lydian, Mixolydian, Aeolian, Harmonic Minor, Melodic Minor. Pentatonic / blues are excluded because stacking thirds for chords behaves inconsistently on a 5-note scale.

Progression (8 bit)

15 progression palette in three groups. Chords are never random:

• Major-flavor: I–V–vi–IV (axis), I–IV–V–I, I–vi–IV–V (50s), ii–V–I–vi (jazz), Pachelbel 8-chord, …
• Minor-flavor: i–VI–III–VII (pop minor), i–VII–VI–V (Andalusian), i–iv–V–i, …
• Modal vamps: Dorian i–IV, Mixolydian I–VII, …

Melody — the heart of the engine

Each 4/4 bar = 16 sixteenth-note slots. Each slot has its own pitch rule:

Cadence rule: the last note of bar 8 → root of the chord currently sounding; the last note of bar 16 → tonic of the scale. Without cadence the music feels "unresolved" — tiring to listen to on loop.

7. On-chain SVG (bits 96..247)

The cover image is generated fully on-chain inside the hook. Three deterministic steps: bit-slice the high half of the seed into 19 fields, pick a layer variant + color for each, render in a fixed z-order.⟨src⟩ contracts/src/svg/AudioMetadata.sol:35-56 :: decode⟨src⟩ contracts/src/svg/SvgGenerator.sol:144-192 :: generateSvg

seed (256 bit)
   │
   │ (1) AudioMetadataLibrary.decode(seed)         — slice bits 96..247
   ▼
{ backGroundColor, frame, frameColor, wave, waveColor,
  motif, motifColor, lead, leadColor, pad, padColor,
  bass, bassColor, drum, drumColor, fx, fxColor,
  grid, gridColor }                                — 19 × uint8

   │ (2) per layer:
   │       id    = (field      % count) + 1
   │       color = colors[colorField % 36]
   ▼
   Rect[] storage  →  toSvg(color)                  — concat <rect> elements

   │ (3) z-order:
   │       bg → grid → spectrum → frame → pad → bass → drum
   │          → motif → lead → wave → fx
   ▼
   <svg viewBox='0 0 24 24'> ... </svg>

Palette + canvas

• 24×24 shape-rendering="crispEdges" canvas — pixel-art friendly.⟨src⟩ contracts/src/svg/SvgGenerator.sol:59 :: SVG_SIZE = 24
• 36-color primary palette + 6-color background palette, frozen at deploy.⟨src⟩ contracts/src/svg/SvgGenerator.sol:63-70 :: _colors[36]⟨src⟩ contracts/src/svg/SvgGenerator.sol:72-73 :: _backgroundColors[6]
• 10 layer slots: frame · wave · motif · lead · pad · bass · drum · fx · grid · spectrum. Each slot is a mapping(id ⇒ Rect[]) populated by the owner via setFrame(...) / setWave(...) / etc.⟨src⟩ contracts/src/svg/SvgGenerator.sol:76-85 :: layer mappings⟨src⟩ contracts/src/svg/SvgGenerator.sol:102-113 :: setFrame / setWave / ...
• If a layer has zero uploaded variants, it's silently skipped — the SVG is still valid, just simpler.⟨src⟩ contracts/src/svg/SvgGenerator.sol:160-189 :: if (...Count > 0)
• The hook IS the generator: there is no separate image contract.⟨src⟩ contracts/src/AudioHook.sol:32 :: contract AudioHook is BaseHook, SvgGenerator, ...

Combinatorics

With 4 variants per layer and the full palette, the artwork space is6 × 4¹⁰ × 36⁹ ≈ 6.4 × 10²⁰ distinct pieces (10 layers × 4 variants, 9 layer colors × 36 palette, 6 backgrounds; spectrum reuses the frame field and color so it isn't counted separately). Real-world uniqueness is bounded by mint count (10,000), not combination space — no two minted uAUD will visually collide in practice.

8. Determinism contract

Same seed + same on-chain storage → same SVG, byte-for-byte. To preserve this contract:

1. Don't change the decoder — bit layout must freeze post-launch.⟨src⟩ contracts/src/svg/AudioMetadata.sol:35-56 :: decode⟨src⟩ web/src/lib/engine/audioMetadata.ts :: decodeAudioMetadata (TS mirror)
2. Don't change the palette — color indices would map to different hex strings.⟨src⟩ contracts/src/svg/SvgGenerator.sol:63-73 :: _colors / _backgroundColors⟨src⟩ web/src/lib/engine/audioPalette.ts :: COLORS / BACKGROUND_COLORS (TS mirror)
3. Don't change the z-order — render order is part of the contract.⟨src⟩ contracts/src/svg/SvgGenerator.sol:144-192 :: generateSvg⟨src⟩ web/src/lib/engine/audioSvg.ts :: renderAudioSvgFromMetadata (TS mirror)
4. Lock variant counts before first mint. Adding a variant changes (field % count) retroactively for old uAUD.⟨src⟩ contracts/src/svg/SvgGenerator.sol:160-189 :: (m.field % count) + 1
5. Bits 248..255 are reserved. The decoder stops at bit 247 — leave room for future fields.⟨src⟩ contracts/src/svg/AudioMetadata.sol:36-56 :: seed >> 96; 19 × uint8

Off-chain music engine determinism is independent: the PRNG is mulberry32(melodyVar) and the only side-channel is AudioContext sample-rate (timing). There is no Solidity counterpart to cross-check against — bits 0..81 are FE-only. Visual cross-engine parity (TS port ↔ Solidity) can be eyeballed by running forge test --match-path test/Render.t.sol and comparing svg-out/sample-*.svg against the same seeds rendered by renderAudioSvg.⟨src⟩ contracts/test/Render.t.sol :: RenderTest.test_render_sample_svgs