Add owner-gated Base Builder attribution

README.md

@@ -69,6 +69,7 @@ The current source includes:
 - [`docs/release-evidence-index.md`](docs/release-evidence-index.md) — claim-to-evidence map for reviewers, contributors, auditors, partners, and funders
 - [`docs/grant-reviewer-guide.md`](docs/grant-reviewer-guide.md) — concise reviewer routes, safety boundaries, and known limitations
 - [`docs/reviewer-publication-runbook.md`](docs/reviewer-publication-runbook.md) — exact-source manifest and owner-gated publication procedure
+- [`docs/base-builder-attribution.md`](docs/base-builder-attribution.md) — owner-gated Base.dev registration, ERC-8021 configuration and verification
 - [`GOVERNANCE.md`](GOVERNANCE.md) — current decision process, roles, conflicts, funding independence, and succession direction
 - [`MAINTAINERS.md`](MAINTAINERS.md) — current maintainers and the path to shared stewardship
 - [`SECURITY.md`](SECURITY.md) — private vulnerability reporting and safe research boundaries

docs/base-builder-attribution.md

@@ -0,0 +1,55 @@
+# Base Builder Code attribution
+
+OpenEscrow can append an ERC-8021 attribution suffix to user-initiated Base transactions after the
+owner registers and verifies the app on Base.dev. Attribution is disabled by default and no Builder
+Code is hardcoded in source.
+
+## Configuration
+
+1. Register and verify `https://openescrow.io` on <https://base.dev>.
+2. Review Base's current terms, select the real payout address and copy the Builder Code from
+   **Settings → Builder Code**.
+3. Set the public build-time environment variable:
+
+   ```dotenv
+   VITE_BASE_BUILDER_CODE=bc_owner_issued_value
+   ```
+
+4. Build and deploy through the normal reviewed release process.
+
+The value is a public attribution identifier, not a private key or secret. It must still come from
+the owner-controlled Base.dev project and must not be guessed or fabricated.
+
+## Transaction coverage
+
+- Direct Privy transactions receive the suffix through Privy's `dataSuffix` plugin.
+- Wagmi contract writes receive the same suffix through viem's per-transaction `dataSuffix`
+  parameter. This explicit path is required because Privy's plugin is not currently applied to
+  transactions sent through the `@privy-io/wagmi` adapter.
+- When the environment variable is blank, both paths behave exactly as before and append nothing.
+
+No contract upgrade or redeployment is required. ERC-8021 data is appended to calldata and ignored
+by the called contract while Base's offchain indexer records the app attribution.
+
+## Verification
+
+After deployment, submit one authentic Base Sepolia lifecycle transaction—never synthetic volume
+for rewards—and preserve its transaction hash. Verify it in both places:
+
+1. Base's Builder Code validation tool confirms the expected code and ERC-8021 marker.
+2. Base.dev shows the attributed transaction in OpenEscrow's onchain analytics after indexing.
+
+The testnet/mainnet distinction remains explicit. Attribution evidence is not proof of production
+adoption, a grant, or a reward, and no reward should be recorded until an attributable payment is
+received.
+
+## Local checks
+
+```powershell
+cd frontend
+npm run test:client-logic
+npm run build
+```
+
+The client-logic suite verifies that an unset or whitespace-only value disables attribution and
+that an owner-supplied code is trimmed and encoded with the official `ox/erc8021` utility.

frontend/.env.example

@@ -2,6 +2,11 @@
 # Leave unset to retain OpenEscrow's direct injected-wallet fallback.
 VITE_PRIVY_APP_ID=
 
+# Optional Base.dev Builder Code (for example, bc_...). When set, OpenEscrow
+# appends an ERC-8021 attribution suffix to user-initiated Base transactions.
+# Obtain the real code by verifying the app on base.dev; never invent one.
+VITE_BASE_BUILDER_CODE=
+
 # Real card/bank funding must target a supported mainnet stablecoin. Keep this
 # disabled for Base Sepolia, where the free faucet remains the funding method.
 VITE_FIAT_ONRAMP_ENABLED=false