[codex] Add fixed-price drop flow spec

[punk6529]

Summary

Adds the INT-002 fixed-price mint and drop authorization integration flow spec for frontend, mobile, Electron, indexer, operator UI, and backend-signing consumers.

This PR adds docs/integrations/contract-flows.md covering source-of-truth artifacts, preflight reads, EIP-712 and ERC-1271 signing paths, mintDrop submission, events, payment credits, withdrawals, curator reserve accounting, failure states, frontend state transitions, and backend signing-service boundaries. It also adds a checker/test pair so required maturity language, flow-critical terms, source links, and validation commands cannot drift.

The repo remains pre-audit and not production-ready; this is integration documentation and gate coverage only, not public-beta, marketplace, signing-service, or live deployment evidence.

Closes #392.

Validation

Focused checks run in D:\repos\6529Stream-pr-ci-hardening and repeated in the clean publishing clone where relevant:

• python scripts/test_contract_flows.py
• python scripts/check_contract_flows.py
• python scripts/test_integrations_readme.py
• python scripts/check_integrations_readme.py
• python scripts/test_release_readiness.py
• python scripts/check_release_readiness.py
• python scripts/test_release_manifest.py
• python scripts/generate_release_manifest.py --check
• python scripts/test_bytecode_release_proof.py
• python scripts/generate_bytecode_release_proof.py --check
• python scripts/test_release_checksums.py
• python scripts/generate_release_checksums.py --check
• python scripts/test_risk_register.py
• python scripts/check_risk_register.py
• python scripts/generate_risk_register.py --check
• python scripts/check_changelog.py
• python -m py_compile scripts/check_contract_flows.py scripts/test_contract_flows.py
• git diff --check
• powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check.ps1 passed locally at 2026-06-15 09:22 UTC after running outside the workspace sandbox so the installed Foundry binary could execute.

Notes

• Raw ABIs remain generated under ignored out/; the flow points integrators to tracked ABI surface/checksum artifacts and address books.
• The flow explicitly says EIP-712 is the signing/encoding layer and replay protection is storage-backed through consumed/cancelled drop IDs, signer epoch, nonce/salt allocation, and deadline.
• The fixed-price curator reserve is documented as reserved/owed accounting, not immediate withdrawal UX.

Summary by CodeRabbit

• New Features

  • Contract flow specification for fixed-price mint and drop authorization flows, including complete integration requirements

• Documentation

  • New specification covers UI/backend workflows, EIP-712 signing, event handling, credit accounting, failure states, and suggested frontend patterns
  • Integration documentation now references contract flow specification

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 151088d5-0ff2-4c4e-9e92-ebe7496c5f7b

📥 Commits

Reviewing files that changed from the base of the PR and between f4fdb5f and 70712ed.

📒 Files selected for processing (24)

• .github/workflows/ci.yml
• CHANGELOG.md
• Makefile
• README.md
• docs/integrations/README.md
• docs/integrations/contract-flows.md
• docs/release-readiness.md
• ops/AUTONOMOUS_RUN.md
• ops/EXECUTION_BACKLOG.md
• release-artifacts/README.md
• release-artifacts/latest/SHA256SUMS
• release-artifacts/latest/bytecode-release-proof.json
• release-artifacts/latest/release-checksums.json
• release-artifacts/latest/release-manifest.json
• release-artifacts/latest/risk-register.json
• scripts/check.ps1
• scripts/check.sh
• scripts/check_contract_flows.py
• scripts/check_integrations_readme.py
• scripts/check_release_readiness.py
• scripts/generate_release_manifest.py
• scripts/test_contract_flows.py
• scripts/test_integrations_readme.py
• scripts/test_release_readiness.py

---

📝 Walkthrough

Walkthrough

Adds docs/integrations/contract-flows.md, a 345-line fixed-price mint/drop authorization integration flow spec. Introduces scripts/check_contract_flows.py (a Python validator for the doc) and scripts/test_contract_flows.py (its unit test suite), wires both into Makefile targets, CI, and check scripts, extends existing release-readiness and integrations-README checkers, and regenerates all affected release artifacts and checksums.

Changes

INT-002 Fixed-Price Mint Flow Spec

Layer / File(s)	Summary
Fixed-price mint flow spec document docs/integrations/contract-flows.md	New 345-line spec covering required artifact inputs, preflight reads, DropAuthorization construction for saleMode = 1, EIP-712 signing (EOA and ERC-1271), mintDrop submission constraints, indexer event topics, credit/withdrawal accounting, categorized failure states, frontend state machine, and backend signing-service boundary.
check_contract_flows.py validator scripts/check_contract_flows.py	New Python CLI tool that validates contract-flows.md against required headings, phrases, commands, and local link targets; raises ContractFlowsError on any violation and exits 1 with stderr output.
test_contract_flows.py unit tests scripts/test_contract_flows.py	New test module that dynamically imports the checker, builds a minimal valid doc fixture, seeds required link target files, and exercises nine accept/reject test cases covering all validator failure paths.
Gate wiring: Makefile, CI, check scripts, and existing checker extensions Makefile, .github/workflows/ci.yml, scripts/check.sh, scripts/check.ps1, scripts/check_integrations_readme.py, scripts/check_release_readiness.py, scripts/generate_release_manifest.py, scripts/test_integrations_readme.py, scripts/test_release_readiness.py	Adds contract-flows-check Makefile target wired into check, release-manifest, and release-manifest-check; adds CI compile-check and "Contract flow docs" step; extends check.sh/ps1; updates existing checkers with new required phrase, commands, and link target; adds docs/integrations/contract-flows.md to DEFAULT_GOVERNANCE_DOCS; updates matching test fixtures.
Documentation updates README.md, docs/integrations/README.md, docs/release-readiness.md, CHANGELOG.md, release-artifacts/README.md	Links contract-flows.md from README Important Docs, integrations index (consumer-surface table, source-of-truth, canonical artifacts, INT-002 backlog), release-readiness dashboard, CHANGELOG INT-002 entry, and release-artifacts command lists.
Regenerated release artifacts release-artifacts/latest/SHA256SUMS, release-artifacts/latest/bytecode-release-proof.json, release-artifacts/latest/release-checksums.json, release-artifacts/latest/release-manifest.json, release-artifacts/latest/risk-register.json	SHA-256 digests and sizes updated for all affected artifacts after doc and governance-doc additions.
Ops worklog and backlog updates ops/AUTONOMOUS_RUN.md, ops/EXECUTION_BACKLOG.md	AUTONOMOUS_RUN.md status table, PR worklog, and decision log updated for Queue Items 187/188 and PRs #391/#393. EXECUTION_BACKLOG.md marks INT-001 merged and expands the INT-002 entry with prescriptive spec and acceptance criteria.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• 6529-Collections/6529Stream#138: Both PRs extend DEFAULT_GOVERNANCE_DOCS in scripts/generate_release_manifest.py to register a new governance document, creating a direct code-level overlap at the same constant.
• 6529-Collections/6529Stream#106: This PR's contract-flows-check target hooks into the same release-manifest and release-manifest-check Makefile dependency chains introduced by that earlier release-manifest tooling PR.
• 6529-Collections/6529Stream#163: This PR extends REQUIRED_MATURITY_PHRASES, REQUIRED_COMMANDS, and REQUIRED_LINK_TARGETS in scripts/check_release_readiness.py that was first introduced in that Gate G release-readiness dashboard PR.

Poem

🐇 A new doc was born in the warren today,
With EIP-712 fields laid out in array.
The checker now reads every heading with care,
And the CI gate watches—no drift shall be there.
From preflight to signing to credits and more,
The mint-flow is mapped from the basement to floor! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[codex] Add fixed-price drop flow spec' accurately reflects the main deliverable: adding the INT-002 fixed-price mint and drop authorization integration flow specification (docs/integrations/contract-flows.md).
Linked Issues check	✅ Passed	The PR fully satisfies all primary objectives from issue #392: adds comprehensive fixed-price mint/drop authorization flow spec covering preflight reads, EIP-712/ERC-1271 signing, transaction submission, event monitoring, credits/withdrawals, and failure states; adds checker/test coverage [scripts/check_contract_flows.py, scripts/test_contract_flows.py]; wires checks into CI/local gates; maintains maturity boundary.
Out of Scope Changes check	✅ Passed	All changes align with the linked issue scope: the primary spec addition (docs/integrations/contract-flows.md), supporting checker/test scripts, documentation links/references, CI/Makefile/script wiring, and release artifact updates are all in-scope for implementing INT-002.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fixed-price-flow-spec

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[6529bot]

6529bot follow-up commit review - 73b7da5

Verdict: No new findings

This follow-up commit (73b7da5) only updates ops/AUTONOMOUS_RUN.md to fill in the active PR URL (#393), which is accurate bookkeeping and carries no code risk.

Reviewing the full change set: the new doc, checker, tests, and gate wiring are internally consistent. The checker's required headings, phrases, commands, and link targets all match the committed contract-flows.md; the test_contract_flows.py minimal-doc fixture exercises both accept and reject paths including path-escape and missing-file cases. Makefile, check.sh, check.ps1, CI, release-manifest, checksum, and risk-register wiring are all updated coherently, and the maturity/no-overclaim language is preserved.

One minor observation worth confirming (not blocking): the doc asserts payment splits as poster = msg.value/2, curator reserve = msg.value/4, protocol = remainder (contract-flows.md ~"Credits And Withdrawals"). The checker does not verify these numeric ratios against StreamDrops.sol/StreamFixedPricePayments.t.sol, so future contract changes to the split could silently drift from this doc. If you want drift protection here, consider asserting the ratios in the checker or referencing the exact test that pins them. Not required for this PR.

No accessibility/i18n/security concerns apply to this docs-and-tooling change.

[6529bot]

6529bot follow-up commit review - 70712ed

Verdict: No new findings

This follow-up adds two small commits: the AUTONOMOUS_RUN.md PR-state update (PATCH 2/3 filling in the #393 URL, identical bookkeeping to the prior 73b7da5 pattern) and head movement to 70712ed. No code, doc, checker, or test logic changed since the last same-lane review of 73b7da5; the substantive INT-002 spec/checker/test/wiring set was already reviewed there.

The bookkeeping edit is accurate: Active PR now resolves TBD → pull/393, consistent with the PR under review.

Resolved since last review

The prior open observation about the payment-split ratios (poster = msg.value/2, curator reserve = msg.value/4, protocol = remainder) not being drift-protected by the checker remains unaddressed but was explicitly non-blocking, so no action is required. Worth noting it is still an option if you want the checker to pin those ratios against StreamFixedPricePayments.t.sol.

No accessibility/i18n/security concerns apply to this docs-and-bookkeeping change.

[punk6529]

Follow-up clarification: the payment-split drift observation is addressed in latest head 70712ed6bce236c1c96f13a8c1805e5d96a038bc.

Specifically:

• docs/integrations/contract-flows.md now links the split ratios to testFixedPriceMintCreditsProceedsWithoutPushPayouts, testFixedPriceOddWeiRemainderAccruesToProtocolCredit, and testOneWeiFixedPriceRemainderCreditsOnlyProtocol in test/StreamFixedPricePayments.t.sol.
• scripts/check_contract_flows.py now requires msg.value / 2, msg.value / 4, msg.value - posterCredit - curatorReserveCredit, and those three test names.
• scripts/test_contract_flows.py updates the minimal fixture so the checker coverage remains executable.

Focused validation after that change:

• python scripts/test_contract_flows.py
• python scripts/check_contract_flows.py
• python scripts/generate_release_manifest.py --check
• python scripts/generate_bytecode_release_proof.py --check
• python scripts/generate_release_checksums.py --check

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[punk6529]

Merge decision for head 70712ed6bce236c1c96f13a8c1805e5d96a038bc:

• CI run 27539242807 / run number 833 completed successfully.
• Foundry smoke passed, including deployment rehearsal and release artifact gates.
• Windows PowerShell wrapper passed.
• CodeRabbit status is success; latest review says no actionable comments were generated.
• 6529bot verdict is No new findings; the payment-split drift observation was addressed in 70712ed by checker-enforced split terms and linked tests, with follow-up clarification posted.
• Review threads: none.
• Submitted reviews: none.

Proceeding with merge.