# Fairlaunch integration ledger

This is the running record for the complete fairlaunch and Metaplex agent integration in the user-selected `musebook-private` checkout. Update this record when source ownership, interfaces, economic rules or verification changes. Link every result to a saved artifact; distinguish source analysis, local execution and public deployment.

## Source ownership

| Input | Role | Current integration decision |
| --- | --- | --- |
| `$REA_ROOT` | REA 6.4.0 browser/static/source-provenance tooling | Built and used directly; no agent registration or native setup |
| `parallel/fairlaunch/core` | Supplied curve, opening guard, holder weight and vesting rules | Both canonical programs import this crate directly; checked U256 holder math uses pinned `uint`, with host replay dependencies kept outside SBF builds |
| `parallel/fairlaunch/programs` | Supplied Anchor 0.31.1 reference programs | Preserve source provenance; do not reintroduce first-caller administration or unsafe holding-account checks |
| `parallel/fairlaunch/tests/integration` | Supplied LiteSVM lifecycle and real Raydium fixture | Actual Raydium lifecycle passes with measured integer final-price proof; hardened creator runtime also performs the actual 80% sale and unpaid forfeiture |
| `parallel/fairlaunch/detector` | Supplied read-only Pump heuristic scanner | Extract reusable analysis, bound requests and report coverage/unknowns; sampled balances are not current holdings |
| `programs/musebook-fairlaunch` | Hardened launch, escrow, administration and pool adapters | Canonical security foundation; import supplied core and guarded/partial-lock behavior |
| `programs/musebook-holder-rewards` | Funded, namespaced, proof-bound reward vaults | Authenticated remaining-escrow counter, ceil-half holding threshold, permanent claim cutoff and permissionless redirection of all unpaid rewards |
| `programs/musebook-pool-adapters` | Original pinned interface encoders | Actual Raydium initialization/LP burn and Meteora initialization/permanent lock/fee collection |
| `web-react` / `cloudflare` | User-facing workspace, wallet review and public read APIs | Fairlaunch, agent curve association and bounded risk inspection; no automatic signatures |

The initial supplied source/file hashes are recorded in `audit/fairlaunch-2026-10-11/parallel-input-manifest.json`. The earlier `$LEGACY_FAIRLAUNCH_ROOT` path was absent when the task began. The user later supplied the actual workspace under `parallel/fairlaunch`; its code and tests are now explicit inputs.

## Verified baseline before importing the supplied workspace

The successful validator run is saved in `audit/fairlaunch-2026-10-11/local-validator-baseline.json`: **30 checks and 34 local transactions**, using the actual downloaded Raydium and Meteora program bytes. It proves funded holder vesting, canonical launch-origin rejection, capped proportional opening, escrow/refund accounting during pause, curve swaps, real fee deposits, exact graduation boundary, Raydium migration/LP burn, competing canonical-pool rejection, post-migration swaps, Meteora permanent position lock and fee collection. No public-chain transaction was sent.

Baseline custom binary hashes:

- Launch: `713471985183fbebe789a1dbde7e3233d187daefa04b3087f5a44a7674ddeedb`.
- Rewards: `ab1f08458a4d867b320815894d4a385ab5430458589942af0a280f1aaf58b98a`.

The baseline did **not** implement the supplied workspace's partial creator withdrawal/80% threshold scenario, its 24-hour warm-up, its guarded slot window, or a Metaplex agent association. Those are new work; the earlier baseline is not evidence for them.

Frontend baseline: production build and release hash checks passed; all **553 tests** passed; desktop/mobile fairlaunch browser checks passed with no overflow, correct draft export, zero financial broadcasts and no page errors. Lint exited successfully with existing repository warnings. REA evidence and its partial capture scope are indexed in `audit/fairlaunch-2026-10-11/evidence-index.json`.

## Required behavior and evidence

| Requirement | Current proof | Explicit boundary |
| --- | --- | --- |
| Uniform opening, ≤3% address cap | Shared-core tests, hardened 17 launch tests, actual opening and repeated-slot rejection | Caps apply to addresses; fixed-price opening excludes the creator |
| Real mainnet Raydium program tested locally | Binary SHA, supplied LiteSVM lifecycle and hardened validator CPI/swaps | Pinned mainnet bytecode executes in a local runtime; no mainnet transaction |
| Permissionless migration, LP burn, replay rejection | A non-creator migrates; LP supply reaches zero; immediate open-period swap and replay rejection | LP burn discards ongoing Raydium LP fee rights |
| Pre-created canonical pool cannot hijack launch | Attacker creates canonical pool and prefunds exclusive PDA before successful migration | Exclusive signer PDA prevents adoption of the attacker's pool |
| Creator vesting and 80% sale clawback | Hardened actual-sale test; exact 180-day payout and fully vested unpaid forfeiture | Threshold is ceil-half of original escrow; paid fees remain paid |
| Holder points with warm-up | 24 core tests, 4 real Rust replay tests, 7 proof-bridge tests | Explicit v2 accounting; root publication still depends on complete authenticated history |
| Agent identity and bonding curve | 10 client tests and desktop/mobile preview, disabled custom signing and Genesis navigation | New agent reads use controlled fixtures; no public mint or delegation executed |
| Permanent canonical agent token | Existing native Genesis owner-reviewed workflow | A custom metadata association cannot fake a Genesis canonical binding |
| Read-only launch risk detector | 9 engine tests plus route/provider tests, forty-physical-request bound and Chrome race checks | Missing/truncated history stays unknown; sampled balances do not establish current holdings |
| Full documentation | This ledger, source manifests, main guide, agent guide and shared accounting guide | Current test reports and retained baseline are distinct evidence |

## Issues found and fixes that must survive integration

The hardened baseline fixed program-owned keypair impersonation with exact off-curve launch-PDA derivation; isolated holder/creator epochs by immutable namespace; required held-mint identity and owner aggregate events; separated read-only authority identity from writable migration funding; and eliminated reachable account-parser stack overruns. Its original creator policy preserved vested entitlement after full escrow exit. The implemented policy now stops every unpaid creator claim on a threshold breach and permits permissionless redirection of unclaimed fees. This includes vested but unclaimed rewards. The actual 80% sale and exact 180-day boundaries are independently executed in `canonical_creator.rs`.

## Current integration verification

The combined `npm run fairlaunch:check` completed all original 18 steps successfully. The final shared detector CLI adds one independently passing step to subsequent runs. Current validator evidence records **33 checks and 35 local transactions**, with actual Raydium and Meteora program bytes. The Raydium pool received `89,439,164,035` base atoms and `8,045,500,008` quote atoms. Its final-curve cross-product remainder is `7,644,187,720`, strictly less than the effective quote reserve `8,995,500,008`: the deposit differs by less than one base atom, with no percentage tolerance.

The supplied reference lifecycle now measures its actual pre-migration curve reserves as well. Its proof remainder is `70,734,893,610 < 115,005,359,057`. Both tests use the Raydium mainnet binary SHA `b6dbea8cefc2e7d490775ce6115e34a2ba480c0853c359e0bb4043b9381ef09a`.

Current canonical binaries:

- Launch SHA `26d00693bb002466e51b4198ea19d2062db70ff041694d56fef5af1037b278f9`.
- Rewards SHA `374655eef4e7f13f67a08fd38fe6cc13327b274690ac99bde5dcabeb1b807007`.

The hardened creator test claimed `516,641` of a funded `3,000,000` quote atoms after 31 days, withdrew and sold 80% of its original lock, then allowed another wallet to redirect the remaining `2,483,359` atoms. Creator claims failed both before and after redirection; repeated forfeiture failed. Forked executed state also verifies the one-second-before/exact-180-day payout boundary, and that fully vested but unpaid rewards are entirely forfeitable after threshold breach.

Full frontend verification passes **563 tests** and desktop/mobile browser checks, including integrated agent and risk panels, native Genesis navigation, no overflow, no page errors and zero financial broadcasts. The Worker entrypoint dry-run bundle succeeds. Logs and source/binary fingerprints live under `artifacts/fairlaunch-2026-10-11/integration/`; the compact final report and source manifest live in the audit directory. New component lint warnings were corrected and the final frontend artifact is rebuilt and rechecked before handoff.

## Interface and accounting changes

`LaunchParameters` appends `guard_slots: u64` and `max_buys_per_slot: u16`. Buy/sell context makes the trader a writable rent payer and appends the per-launch/wallet PDA plus System program. Order settlement appends its owner's wallet PDA. `claim_creator_tokens(amount: u64)` permits partial release; authenticated `creator_exit(remaining: u64)` updates the rewards counter atomically. `CreatorCollateral.current_locked` excludes other reserve tokens in the shared vault. `clawback_creator` moves outstanding, unexported creator fees into holder liabilities. Instruction metadata is regenerated by source readers, explicitly **not** a compiler-generated Anchor IDL.

Shared core changes reject invalid reserves/fees/timestamps, prevent truncating casts, calculate the final gross fee consistently, and make failed mutations atomic. Holder arithmetic integrates the multiplier continuously and carries rational remainders, so no-op checkpoints cannot increase rewards. New v2 replay uses 24-hour warm-up, pending top-up rewarming and loyalty resets after eligible balance reductions. The older lot-based v1 publisher remains separately labeled. See [shared accounting](/research/fairlaunch/holder-accounting.md).

Ten attachment hashes and installed SDK versions are in agent-doc-inputs.json (`audit/fairlaunch-2026-10-11/agent-doc-inputs.json`). [Agent integration](/research/fairlaunch/agents.md) explains Core asset, Identity PDA, Asset Signer and fungible mint identities; native Genesis binding; custom association drafts; and the existing finance, commerce and Nori boundaries.

The supplied detector CLI now imports the same Worker-safe engine as the API. Its original source/package hashes are retained in detector provenance (`parallel/fairlaunch/detector/provenance.json`). CLI usage (`parallel/fairlaunch/detector/README.md`) requires `RPC_URL` or explicit public-RPC selection, caps physical reads at forty, performs no retries or redirects and redacts provider details. Nine CLI/transport/executable fixtures pass; incomplete coverage exits with a partial/unknown report and `riskScore: null`.

The supplied reference programs currently need administration, immutable minting, escrow accounting and holding-account hardening before becoming user-facing programs. In particular, a user-owned empty token account must not enable an attacker to forfeit another holder's allocation; current holding evidence must identify the registered account or an authenticated aggregate.

## Metaplex attachment inventory

Ten pasted guides were read and assigned to the agent integration review: mint an agent; register identity; read agent data; agent finance; agent commerce; create an agent token; run an agent; Nori overview; Nori delegation; Nori examples. Their distinctions matter: Core asset URI and registration metadata are separate, the Asset Signer is a PDA, canonical token binding requires Genesis, execution delegation is owner-controlled, and Nori service calls can spend real funds. No paid call, delegation or public mint is authorized merely by importing these references. UI preparation and verification preserve wallet review.

## Accurate competitive claims

The published Pump SOL/USDC curve schedule is 1.25%, including 0.30% creator/holder fees. Pump supports opt-in holder-reward coins, custom quote pairs and eligible Pump coin quotes. Do not repeat "Pump gives holders nothing" or market agent-token quotes as unique. State the proposed 1% curve split explicitly, keep address caps distinct from identity controls, and describe uniform accepted-order pricing without promising Sybil resistance or rug prevention. Post-graduation Raydium LP burn discards ongoing fee rights; Meteora locked positions retain fee collection but an existing customizable pool can block migration liveness.

## Deployment and outstanding boundaries

Everything here is source and local-test work. Custom programs remain undeployed. Public deployment, live indexing, funded wallet execution, production agent callbacks and outside security review have separate evidence requirements. The held-mint replay input and root publisher remain trust boundaries. Preserve the existing user data and unrelated worktree changes.

## Reader article and documentation publication

The canonical article is `web-react/src/content/fairlaunch-agent-economy.md`, mirrored into [FAIRLAUNCH_ARTICLE.md](/research/fairlaunch-agent-economy.md) by `web-react/scripts/build-fairlaunch-article.mjs`. The site route `/fairlaunch/article/` presents the full report with a lifecycle diagram, accessible curve-fee illustration, section navigation and PDF/Markdown downloads. `/docs/#fairlaunch`, the fairlaunch workspace, site navigation and `llms.txt` link to it.

Publication artifacts use a separate `research/fairlaunch-article-manifest.json`; the older whitepaper manifest and the saved integration verification baseline are preserved. Developer guides and selected structured evidence are published as sanitized copies under `research/fairlaunch/`, with current publication hashes and no private filesystem paths. The article states the actual local execution scope, creator-sale and price-continuity results, existing Pump holder rewards, root-publisher trust and undeployed custom programs. Article build, artifact tests and desktop/mobile browser checks validate this documentation change separately from the saved program lifecycle tests.