New launch model: Shards — locked bonding-curve market for a fixed on-chain-art NFT collection

.github/workflows/mainnet-evidence.yml

@@ -8,6 +8,7 @@ on:
     paths:
       - "src/**"
       - "test/ClassicV3MainnetFork.t.sol"
+      - "test/ShardV1MainnetFork.t.sol"
       - "deployments/**"
       - "models/**"
       - "releases/**"
@@ -54,3 +55,15 @@ jobs:
             done
           done
           exit 1
+
+      - name: Run Shards lifecycle fork test
+        run: |
+          for rpc_url in https://rpc.flashbots.net https://eth.drpc.org; do
+            for attempt in 1 2; do
+              echo "Fork attempt ${attempt} with ${rpc_url}"
+              if ETHEREUM_RPC_URL="${rpc_url}" forge test --match-contract ShardV1MainnetForkTest; then
+                exit 0
+              fi
+            done
+          done
+          exit 1

.github/workflows/security.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Measure source coverage
         run: >-
           forge coverage
-          --no-match-contract ClassicV3MainnetForkTest
+          --no-match-contract '(ClassicV3MainnetForkTest|ShardV1MainnetForkTest)'
           --exclude-tests
           --report lcov
           --report-file lcov.info

MODELS.md

@@ -10,6 +10,7 @@ accounted for. [`models/registry.json`](models/registry.json) is the canonical m
 | Classic | **Available** | [`classic-v3`](releases/classic-v3/RELEASE.md) | [Open model](models/classic/README.md) |
 | Stock-Paired | **Candidate** | Deployed candidate | [Open candidate](models/stock-paired/README.md) |
 | Deep | **Design** | None | [Open design](models/deep/README.md) |
+| Shards | **Design** | None | [Open design](models/shards/README.md) |
 
 `Available` means the exact source, parameters, deployment, runtime hashes and security status are public. It does not
 mean that a model has received an independent audit.
@@ -77,6 +78,19 @@ is reached. It has no deployed contracts and is not available for launch.
 
 [Design and open release gates](models/deep/README.md)
 
+## Shards
+
+**Design only.** Shards proposes a single-sided bonding-curve market for a fixed 10,000-piece on-chain-art NFT
+collection. Each launch deploys its own hook, token and NFT contract through an atomic factory and uses that
+factory's shared renderer; the whole supply is locked into a
+permanent Uniswap v4 position with no withdrawal path, and art is regenerated on every acquisition from the pool.
+Its 1.00% native-ETH swap fee is split 0.80% to collection holders, 0.10% to the hook builder and 0.10% to
+Programmable. It has no deployed contracts and is not available for launch.
+
+[Design and open release gates](models/shards/README.md) ·
+[Security properties](models/shards/SECURITY.md) ·
+[Fixed parameters](spec/shards-v1.json)
+
 ## Adding a model
 
 New models start at `design`. They become `candidate` only after source, tests, fixed parameters and security properties

docs/SHARDS_LAUNCH_RUNBOOK.md

@@ -0,0 +1,150 @@
+# Shards V1 launch runbook
+
+This runbook reproduces a Shards launch from canonical source. It deliberately separates factory deployment, salt mining, and launch broadcast. The factory is deployed through the canonical CREATE2 proxy, so its address depends only on the factory salt and init-code — never on the deployer's nonce — and can be predicted and reproduced by any sender.
+
+Shards remains in `design` status. None of the commands below authorizes a production deployment.
+
+## Fixed inputs
+
+- Ethereum PoolManager: `0x000000000004444c5dc75cB358380D2e3dE08A90`
+- CREATE2 deployment proxy: `0x4e59b44847b379578588920cA78FbF26c0B4956C`
+- factory deployer (EOA that broadcasts): `0x2Bb333d48DFAF1596D9036671d2E43168994249E`
+- launcher (Programmable 0.10%) recipient: `0x4957f49620AFf3Adbbe8195a4f633E49cc93376c` — an immutable constant in `ShardLaunchFactoryV1`, not a constructor argument
+- builder (0.10%) recipient: `0xceeBB3A6543CeBEB2ED66963897A0abEA52A50cC`
+- factory salt: `0x655a4b5a2b704bef84b4ff94adde0a7ac40ad0366c82ddca5290180fe4c3986d` (`keccak256("programmable.shards-v1.factory.v1")`)
+- raw token salt: `0xca9944c923e24ba5cb3188a29b18c3305158e686e39473e91bbe31fc019816ab` (`keccak256("programmable.shards-v1.token.v1")`)
+- hook creation-code hash: `0x34df1ce932b3ca8eebc45eff8116378cbcd5a4a285fd2bf0c28bd78a350d8a2f`
+- tick spacing: `60`
+- production tick lower: `-887220`
+- production tick band: `22980`
+- production tick upper: `69060`
+- production start price: `TickMath.getSqrtPriceAtTick(69060)`
+- required low hook bits: exactly `beforeInitialize`, `beforeSwap`, `afterSwap`, `beforeSwapReturnDelta`, and `afterSwapReturnDelta`
+
+The full pinned plan — factory, renderer, effective token salt, mined hook salt, predicted SHARD/hook/NFT, and expected configuration hash — is recorded in `releases/shards-v1/mainnet-manifest.json` under `candidatePlan`. Every one of those values is valid only for the exact reviewed source at this revision; any source change invalidates them and requires re-mining.
+
+## 1. Build and inspect artifacts
+
+```bash
+./scripts/bootstrap-deps.sh
+forge fmt --check
+forge build --sizes
+forge inspect ShardHookV1 bytecode | cast keccak
+forge inspect ShardHookV1 deployedBytecode | cast keccak
+forge inspect ShardLaunchFactoryV1 bytecode | cast keccak
+forge inspect ShardLaunchFactoryV1 deployedBytecode | cast keccak
+```
+
+`bytecode` is the constructor-free creation-code artifact. Record it separately from full deployment initcode, which appends constructor arguments. Every runtime must remain below 24,576 bytes and full factory deployment initcode must remain below 49,152 bytes. `keccak256` of the `ShardHookV1` creation-code artifact must equal the hook creation-code hash in Fixed inputs.
+
+## 2. Predict the factory address (no broadcast)
+
+The factory address is nonce-independent — it is `CREATE2(proxy, factorySalt, keccak256(initcode))` — so it can be checked before any transaction:
+
+```bash
+forge script script/LaunchShardsV1.s.sol:LaunchShardsV1 \
+  --rpc-url "$ETHEREUM_RPC_URL" \
+  --sig "previewFactory(address,bytes32,bytes32)" \
+  0x000000000004444c5dc75cB358380D2e3dE08A90 "$HOOK_CODE_HASH" "$FACTORY_SALT"
+```
+
+Confirm the printed factory and renderer equal the `candidatePlan` values. No nonce is involved; the prediction does not change if the deployer sends other transactions first.
+
+## 3. Deploy the factory through the CREATE2 proxy
+
+After explicit deployment authorization, use a configured hardware wallet or encrypted Foundry account:
+
+```bash
+forge script script/LaunchShardsV1.s.sol:LaunchShardsV1 \
+  --rpc-url "$ETHEREUM_RPC_URL" --account "$FOUNDRY_ACCOUNT" --broadcast \
+  --sig "deployFactory(address,bytes32,bytes32)" \
+  0x000000000004444c5dc75cB358380D2e3dE08A90 "$HOOK_CODE_HASH" "$FACTORY_SALT"
+```
+
+`deployFactory` reverts unless the supplied hash equals `keccak256(type(ShardHookV1).creationCode)` and unless the deployed address equals the CREATE2 prediction. Verify `poolManager`, `launcherFeeRecipient`, `renderer`, and `hookCreationCodeHash` from chain state. Verify the factory and shared renderer source using the exact build settings in `foundry.toml`.
+
+Never put a private key, mnemonic, API token, or broadcast secret in a command line, repository file, shell history, or plan. Use a hardware signer or encrypted account prompt.
+
+## 4. Mine twice against the factory
+
+Mining is a non-broadcast view call. Use identical inputs twice and save both complete outputs:
+
+```bash
+forge script script/LaunchShardsV1.s.sol:LaunchShardsV1 \
+  --rpc-url "$ETHEREUM_RPC_URL" \
+  --sig "predictAndMine(address,bytes32,bytes32,(int24,int24,int24,uint160,address))" \
+  "$FACTORY" "$TOKEN_SALT" 0x0 \
+  "(-887220,22980,69060,$START_SQRT_PRICE_X96,$BUILDER)"
+```
+
+Repeat the exact command from a clean shell. The raw and effective salts, creation-code and initcode hashes, predicted SHARD, hook and NFT, expected configuration hash, and mined hook salt must match byte-for-byte, and must equal the `candidatePlan` values. Confirm the hook's low 14 bits equal the exact required mask.
+
+## 5. Simulate the canonical launch
+
+```bash
+forge script script/LaunchShardsV1.s.sol:LaunchShardsV1 \
+  --rpc-url "$ETHEREUM_RPC_URL" \
+  --sender "$DEPLOYER" \
+  --sig "launch(address,bytes32,bytes32,(int24,int24,int24,uint160,address))" \
+  "$FACTORY" "$TOKEN_SALT" "$HOOK_SALT" \
+  "(-887220,22980,69060,$START_SQRT_PRICE_X96,$BUILDER)"
+```
+
+Run this against a block at or after the confirmed factory receipt. For an offline rehearsal, replay factory deployment and launch in the same local fork. The returned SHARD, hook, and NFT must equal the mined predictions, and the configuration hash must equal the pre-broadcast commitment. Confirm the simulation emits one `ShardLaunched` event and leaves the factory with zero SHARD.
+
+## 6. Broadcast one launch
+
+Only after the source-review, security-review, and explicit deployment-authorization gates are satisfied:
+
+```bash
+forge script script/LaunchShardsV1.s.sol:LaunchShardsV1 \
+  --rpc-url "$ETHEREUM_RPC_URL" --account "$FOUNDRY_ACCOUNT" --broadcast \
+  --sig "launch(address,bytes32,bytes32,(int24,int24,int24,uint160,address))" \
+  "$FACTORY" "$TOKEN_SALT" "$HOOK_SALT" \
+  "(-887220,22980,69060,$START_SQRT_PRICE_X96,$BUILDER)"
+```
+
+Do not retry blindly. First inspect the transaction and `configurationHashOf(predictedHook)`. An exact-configuration observer can sponsor the public launch before the intended sender; that creates the same contracts and recipients rather than redirecting the builder role.
+
+## 7. Post-launch verification
+
+Verify exact source for the factory, renderer, hook, SHARD, and NFT. Then independently:
+
+1. recompute the effective token salt from the raw salt, hook salt, ticks, start price, and builder recipient;
+2. recompute token, hook, and NFT CREATE2 addresses from the factory;
+3. hash the actual `ShardHookV1` creation bytes and exact constructor initcode;
+4. recompute the configuration hash in the field order used by `ConfigurationData`;
+5. check `configurationHashOf(hook)` and the `ShardLaunched` event;
+6. check the exact five hook permission bits and PoolManager authentication;
+7. check `hook.deployer() == factory`, NFT-to-hook and hook-to-NFT back-references, and consumed one-shot powers;
+8. check both liquidity positions and the SHARD/NFT backing identity.
+
+A second launch with the same raw token salt, builder, and hook salt must revert because the predicted addresses are occupied. It must not change the first launch.
+
+## Rehearsal record
+
+The predicted plan was generated deterministically from the reviewed source: the factory address was computed as `CREATE2(0x4e59…4956C, factorySalt, keccak256(initcode))`, the factory was deployed at that address through a CREATE2 deployer to run its constructor (which deploys the shared renderer), and the hook salt was mined against it. Pinned outputs (all recorded in `candidatePlan`):
+
+```text
+expected factory:            0xDc1Aae9A32c5220dAAE2CCD4D10329bEb854bf39
+expected renderer:           0x3C8B0168a345116A7f40d866D07b3aed832D0812
+launcher fee recipient:      0x4957f49620AFf3Adbbe8195a4f633E49cc93376c
+builder fee recipient:       0xceeBB3A6543CeBEB2ED66963897A0abEA52A50cC
+hook creation-code hash:     0x34df1ce932b3ca8eebc45eff8116378cbcd5a4a285fd2bf0c28bd78a350d8a2f
+raw token salt:              0xca9944c923e24ba5cb3188a29b18c3305158e686e39473e91bbe31fc019816ab
+effective token salt:        0xe1387dff2e86548ec4a0a8e8678c4b55d50b64f522ba7681cf3c3f5535ca6d4a
+hook salt:                   0x00000000000000000000000000000000000000000000000000000000000031ec
+predicted SHARD:             0x92541FCEd29417859d1eA3fC6a9506464FC51D94
+predicted hook:              0x8Add9914734D3178a296e8C007Ab2F22559Ea0cC
+predicted NFT:               0x62D7bD7F95eE7e35956f76531757C9514a4b762b
+expected configuration hash: 0x475e4ee8be4b757b4e10fffbd5410a145eac6c05a44a7904c03d4504934e639c
+```
+
+The pinned Mainnet-fork suite reproduces the full lifecycle against the canonical v4 PoolManager:
+
+```text
+ETHEREUM_RPC_URL=https://eth.drpc.org forge test --match-contract ShardV1MainnetForkTest -vv
+  4 passed; factory deployment gas 7,176,677; atomic launch gas 8,532,815; block 25639000
+```
+
+The factory unit suite separately covers deterministic re-mining, failure after each deployment stage with full rollback, and a duplicate launch reverting `AddressOccupied` without changing the first launch.