[codex] Add wallet signature integration guide

.github/workflows/ci.yml

@@ -171,6 +171,8 @@ jobs:
             scripts/test_contract_flows.py \
             scripts/check_auction_flows.py \
             scripts/test_auction_flows.py \
+            scripts/check_wallet_signature_flows.py \
+            scripts/test_wallet_signature_flows.py \
             scripts/check_release_readiness.py \
             scripts/test_release_readiness.py \
             scripts/generate_release_manifest.py \
@@ -474,6 +476,8 @@ jobs:
           python3 scripts/check_contract_flows.py 2>&1 | tee ci-logs/contract-flows-check.log
           python3 scripts/test_auction_flows.py 2>&1 | tee ci-logs/auction-flows-tests.log
           python3 scripts/check_auction_flows.py 2>&1 | tee ci-logs/auction-flows-check.log
+          python3 scripts/test_wallet_signature_flows.py 2>&1 | tee ci-logs/wallet-signature-flows-tests.log
+          python3 scripts/check_wallet_signature_flows.py 2>&1 | tee ci-logs/wallet-signature-flows-check.log
 
       - name: Release readiness
         shell: bash

CHANGELOG.md

@@ -7,6 +7,13 @@ the release policy in `docs/release-policy.md`.
 
 ### Added
 
+- Added INT-004 wallet, EIP-712, ERC-1271, and Safe signing guide with
+  `docs/integrations/wallets-and-signatures.md`, a checker/test pair,
+  local/CI gate wiring, release-readiness navigation, and release-manifest
+  coverage so React, mobile, Electron, operator UI, indexer, and backend
+  signing-service teams can trace domain fields, replay controls, EOA and
+  contract-signer behavior, Safe/WalletConnect caveats, failure states, and
+  no-secret custody boundaries without production-readiness overclaims.
 - Added INT-003 auction frontend and indexer flow spec with
   `docs/integrations/auction-flows.md`, a checker/test pair, local/CI gate
   wiring, release-readiness navigation, and release-manifest coverage so

Makefile

@@ -26,9 +26,9 @@ RM_RF := rm -rf out cache broadcast
 endif
 PATH := $(FOUNDRY_BIN)$(PATH_SEPARATOR)$(REPO_ROOT)/$(VENV_BIN)$(PATH_SEPARATOR)$(PATH)
 
-.PHONY: check build test gas-snapshot gas-snapshot-check size deploy-rehearsal metadata-fixtures-check windows-check-wrapper-policy windows-check-wrapper-runtime drop-authorization-fixtures-check drop-authorization-signing-evidence-check signer-custody-readiness-check admin-ceremony-evidence-check solidity-formatting-check release-artifacts release-artifacts-check source-verification-inputs source-verification-inputs-check abi-compatibility abi-compatibility-check broadcast-manifest-inputs broadcast-manifest-inputs-check deployment-manifests deployment-manifest-check address-books address-books-check dependency-artifacts dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check signed-release-tag-check bytecode-release-proof bytecode-release-proof-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check public-beta-evidence-check public-beta-blocker-report public-beta-blocker-report-check production-release-blocker-report production-release-blocker-report-check release-evidence-packet-index release-evidence-packet-index-check release-evidence-issue-backlog release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-labels-check release-evidence-issue-body-sync release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-report-check release-evidence-live-audit-markdown-check release-evidence-live-audit-archive release-evidence-live-audit-archive-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check release-readiness-check release-manifest release-manifest-check release-checksums release-checksums-check changelog-check fmt-check slither clean
+.PHONY: check build test gas-snapshot gas-snapshot-check size deploy-rehearsal metadata-fixtures-check windows-check-wrapper-policy windows-check-wrapper-runtime drop-authorization-fixtures-check drop-authorization-signing-evidence-check signer-custody-readiness-check admin-ceremony-evidence-check solidity-formatting-check release-artifacts release-artifacts-check source-verification-inputs source-verification-inputs-check abi-compatibility abi-compatibility-check broadcast-manifest-inputs broadcast-manifest-inputs-check deployment-manifests deployment-manifest-check address-books address-books-check dependency-artifacts dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check signed-release-tag-check bytecode-release-proof bytecode-release-proof-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check public-beta-evidence-check public-beta-blocker-report public-beta-blocker-report-check production-release-blocker-report production-release-blocker-report-check release-evidence-packet-index release-evidence-packet-index-check release-evidence-issue-backlog release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-labels-check release-evidence-issue-body-sync release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-report-check release-evidence-live-audit-markdown-check release-evidence-live-audit-archive release-evidence-live-audit-archive-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check wallet-signature-flows-check release-readiness-check release-manifest release-manifest-check release-checksums release-checksums-check changelog-check fmt-check slither clean
 
-check: build test gas-snapshot-check size solidity-formatting-check windows-check-wrapper-policy metadata-fixtures-check drop-authorization-fixtures-check drop-authorization-signing-evidence-check signer-custody-readiness-check admin-ceremony-evidence-check release-artifacts-check source-verification-inputs-check abi-compatibility-check signed-release-tag-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check public-beta-evidence-check public-beta-blocker-report-check production-release-blocker-report-check release-evidence-packet-index-check release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-labels-check release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-archive-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check release-readiness-check release-checksums-check changelog-check deploy-rehearsal
+check: build test gas-snapshot-check size solidity-formatting-check windows-check-wrapper-policy metadata-fixtures-check drop-authorization-fixtures-check drop-authorization-signing-evidence-check signer-custody-readiness-check admin-ceremony-evidence-check release-artifacts-check source-verification-inputs-check abi-compatibility-check signed-release-tag-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check public-beta-evidence-check public-beta-blocker-report-check production-release-blocker-report-check release-evidence-packet-index-check release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-labels-check release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-archive-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check wallet-signature-flows-check release-readiness-check release-checksums-check changelog-check deploy-rehearsal
 
 build:
 	forge build
@@ -278,14 +278,18 @@ auction-flows-check:
 	$(PYTHON) scripts/test_auction_flows.py
 	$(PYTHON) scripts/check_auction_flows.py
 
+wallet-signature-flows-check:
+	$(PYTHON) scripts/test_wallet_signature_flows.py
+	$(PYTHON) scripts/check_wallet_signature_flows.py
+
 release-readiness-check:
 	$(PYTHON) scripts/test_release_readiness.py
 	$(PYTHON) scripts/check_release_readiness.py
 
-release-manifest: address-books source-verification-inputs dependency-artifacts ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check drop-authorization-signing-evidence-check signer-custody-readiness-check public-beta-evidence-check risk-register public-beta-blocker-report-check production-release-blocker-report-check release-evidence-packet-index-check release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-markdown-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check drop-authorization-fixtures-check release-readiness-check
+release-manifest: address-books source-verification-inputs dependency-artifacts ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check drop-authorization-signing-evidence-check signer-custody-readiness-check public-beta-evidence-check risk-register public-beta-blocker-report-check production-release-blocker-report-check release-evidence-packet-index-check release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-markdown-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check wallet-signature-flows-check drop-authorization-fixtures-check release-readiness-check
 	$(PYTHON) scripts/generate_release_manifest.py
 
-release-manifest-check: address-books-check source-verification-inputs-check dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check drop-authorization-signing-evidence-check signer-custody-readiness-check public-beta-evidence-check risk-register-check public-beta-blocker-report-check production-release-blocker-report-check release-evidence-packet-index-check release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-markdown-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check drop-authorization-fixtures-check release-readiness-check
+release-manifest-check: address-books-check source-verification-inputs-check dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check external-audit-report-evidence-check fork-deployment-rehearsal-evidence-check testnet-deployment-rehearsal-evidence-check drop-authorization-signing-evidence-check signer-custody-readiness-check public-beta-evidence-check risk-register-check public-beta-blocker-report-check production-release-blocker-report-check release-evidence-packet-index-check release-evidence-issue-backlog-check release-evidence-issue-links-check release-evidence-issue-body-sync-check release-evidence-issue-bodies-check release-evidence-issue-closure-check release-evidence-live-audit-markdown-check architecture-threat-model-check audit-package-check incident-response-check integrations-readme-check contract-flows-check auction-flows-check wallet-signature-flows-check drop-authorization-fixtures-check release-readiness-check
 	$(PYTHON) scripts/test_release_manifest.py
 	$(PYTHON) scripts/generate_release_manifest.py --check
 

docs/drop-authorization-signing.md

@@ -16,6 +16,9 @@ the target-state Solidity coverage lives in
 [`test/StreamDropsEIP712.t.sol`](../test/StreamDropsEIP712.t.sol),
 [`test/StreamDropsERC1271.t.sol`](../test/StreamDropsERC1271.t.sol), and
 [`test/helpers/DropAuthTestHelper.sol`](../test/helpers/DropAuthTestHelper.sol).
+For app-facing wallet, Safe, WalletConnect, frontend preflight, and UX failure
+handling, use
+[`docs/integrations/wallets-and-signatures.md`](integrations/wallets-and-signatures.md).
 
 This guide covers:
 
@@ -317,4 +320,5 @@ Required cross-links:
 - [`docs/audit-package.md`](audit-package.md)
 - [`docs/incident-response.md`](incident-response.md)
 - [`docs/signer-custody-readiness.md`](signer-custody-readiness.md)
+- [`docs/integrations/wallets-and-signatures.md`](integrations/wallets-and-signatures.md)
 - [`ops/ROADMAP.md`](../ops/ROADMAP.md)

docs/integrations/README.md

@@ -34,12 +34,12 @@ Supported consumer categories for this entrypoint:
 
 | Consumer | Current entrypoint | Status |
 | --- | --- | --- |
-| React web app | Use the generated address books, ABI surface/checksum artifacts, signing docs, metadata docs, release-readiness dashboard, [`contract-flows.md`](contract-flows.md), and [`auction-flows.md`](auction-flows.md) | Fixed-price and auction flows are documented; other detailed flow specs remain future `INT` work |
-| Mobile app | Use the same contract surface artifacts plus wallet/signing docs, [`contract-flows.md`](contract-flows.md), and [`auction-flows.md`](auction-flows.md) | Fixed-price and auction flows are documented; WalletConnect and deep-link guidance remains future `INT-008` work |
-| Electron app | Use web-app artifacts plus strict renderer/process security assumptions | Entry point only; Electron security guidance remains future `INT-009` work |
+| React web app | Use the generated address books, ABI surface/checksum artifacts, signing docs, metadata docs, release-readiness dashboard, [`contract-flows.md`](contract-flows.md), [`auction-flows.md`](auction-flows.md), and [`wallets-and-signatures.md`](wallets-and-signatures.md) | Fixed-price, auction, and wallet/signature flows are documented; other detailed flow specs remain future `INT` work |
+| Mobile app | Use the same contract surface artifacts plus [`wallets-and-signatures.md`](wallets-and-signatures.md), [`contract-flows.md`](contract-flows.md), and [`auction-flows.md`](auction-flows.md) | Fixed-price, auction, WalletConnect, and mobile handoff signature guidance are documented; deeper mobile reference architecture remains future `INT-008` work |
+| Electron app | Use web-app artifacts plus [`wallets-and-signatures.md`](wallets-and-signatures.md) and strict renderer/process security assumptions | Signature boundary guidance is documented; deeper Electron shell guidance remains future `INT-009` work |
 | Indexer | Use event topic catalog, interface IDs, deployment manifests, address books, release manifest, and [`auction-flows.md`](auction-flows.md) | Auction lifecycle reconstruction is documented; full event replay spec remains future `INT-005` work |
 | Operator UI | Use deployment docs, ceremony evidence, randomizer operations docs, risk register, and release-readiness dashboard | Entry point only; dashboard query model remains future `GOV`/`INT` work |
-| Backend signing service | Use EIP-712, ERC-1271, signer custody, and drop authorization signing docs | Local templates only; production signing evidence remains blocked |
+| Backend signing service | Use EIP-712, ERC-1271, Safe, signer custody, drop authorization signing docs, and [`wallets-and-signatures.md`](wallets-and-signatures.md) | Local templates and integration guidance only; production signing evidence remains blocked |
 
 ## Source Of Truth
 
@@ -70,6 +70,7 @@ Use tracked generated artifacts rather than hand-maintained copies.
 | Drop signing | [`docs/drop-authorization-signing.md`](../drop-authorization-signing.md) | EIP-712 and ERC-1271 local fixture guidance |
 | Fixed-price mint flow | [`docs/integrations/contract-flows.md`](contract-flows.md) | Current `INT-002` transaction, event, credit, and failure-state guide |
 | Auction flow | [`docs/integrations/auction-flows.md`](auction-flows.md) | Current `INT-003` auction submit, bid, settlement, credit, pause, and indexer guide |
+| Wallet and signature guide | [`docs/integrations/wallets-and-signatures.md`](wallets-and-signatures.md) | Current `INT-004` EIP-712, ERC-1271, Safe, WalletConnect, backend signer, and failure-state guide |
 | Release signatures | [`docs/release-signatures.md`](../release-signatures.md) | No production signatures are committed |
 
 ## Canonical Artifacts
@@ -91,6 +92,7 @@ can prove the entrypoint keeps all required local targets reachable:
 - [`docs/known-blockers.md`](../known-blockers.md)
 - [`docs/integrations/contract-flows.md`](contract-flows.md)
 - [`docs/integrations/auction-flows.md`](auction-flows.md)
+- [`docs/integrations/wallets-and-signatures.md`](wallets-and-signatures.md)
 - [`release-artifacts/README.md`](../../release-artifacts/README.md)
 - [`release-artifacts/contracts.json`](../../release-artifacts/contracts.json)
 - [`release-artifacts/baselines/v0.1.0/abi-surface.json`](../../release-artifacts/baselines/v0.1.0/abi-surface.json)
@@ -123,7 +125,8 @@ to understand what is still intentionally future work:
   [`contract-flows.md`](contract-flows.md).
 - `INT-003`: auction frontend and indexer flow spec is now
   [`auction-flows.md`](auction-flows.md).
-- `INT-004`: wallet, EIP-712, ERC-1271, and Safe signing guide.
+- `INT-004`: wallet, EIP-712, ERC-1271, and Safe signing guide is now
+  [`wallets-and-signatures.md`](wallets-and-signatures.md).
 - `INT-005`: event and indexer reconstruction spec.
 - `INT-006`: metadata rendering, cache, animation sandbox, and marketplace
   integration guide.
@@ -161,6 +164,8 @@ python scripts/test_integrations_readme.py
 python scripts/check_integrations_readme.py
 python scripts/test_auction_flows.py
 python scripts/check_auction_flows.py
+python scripts/test_wallet_signature_flows.py
+python scripts/check_wallet_signature_flows.py
 python scripts/check_release_readiness.py
 python scripts/check_changelog.py
 ```