Enforce Core UTF-8 metadata policy

[punk6529]

Summary

• Enforce strict UTF-8 validation for StreamCore production metadata inputs by reusing linked StreamMetadataRenderer guard helpers.
• Preserve size-before-UTF-8 error ordering across collection fields, scripts, token data, token image values, token raw attributes, and generated tokenURI output.
• Recover enough Core bytecode headroom with renderer-linked guard consolidation plus TokenNotMinted() for Core minted checks.
• Refresh metadata/status docs, roadmap state, changelog, release artifacts, deployment examples, address books, source-verification inputs, and checksum bundles.

Closes #125.

Size Evidence

• StreamCore: 24,160 runtime bytes, 416 bytes of EIP-170 headroom.
• StreamMetadataRenderer: 10,442 runtime bytes after shared guard helpers.
• Current Core margin remains above the 384-byte minimum release floor and below the 512-byte warning threshold documented for future non-trivial Core work.

Local Verification

• forge test --match-path test/StreamMetadataUtf8.t.sol -vvv
• forge test --match-path test/StreamCoreCustomErrors.t.sol -vvv
• forge test --match-path test/StreamMetadataUriPolicy.t.sol -vvv
• forge build --sizes --via-ir --skip test --skip script --force
• make release-checksums
• make check
• scripts\check.ps1
• forge fmt --check smart-contracts/StreamCore.sol smart-contracts/StreamMetadataRenderer.sol test/StreamMetadataUtf8.t.sol test/StreamCoreCustomErrors.t.sol test/StreamMetadataUriPolicy.t.sol
• git diff --check

Summary by CodeRabbit

Release Notes

• New Features

  • StreamCore metadata validation now enforces strict UTF-8 character encoding across collection fields, script chunks, token data, image URIs, and raw attributes.

• Improvements

  • Enhanced error handling with specific custom error types for validation failures. Optimized contract efficiency by consolidating reusable validation logic into a shared library.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[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: 5c309b68-dc8d-4454-805e-88531722c3f7

📥 Commits

Reviewing files that changed from the base of the PR and between 2865658 and efd74a3.

📒 Files selected for processing (21)

• CHANGELOG.md
• deployments/address-books/anvil-6529stream-v0.1.0-001-broadcast.json
• deployments/address-books/anvil-6529stream-v0.1.0-001.json
• deployments/examples/anvil-6529stream-v0.1.0-001-broadcast.json
• deployments/examples/anvil-6529stream-v0.1.0-001.json
• docs/known-blockers.md
• docs/metadata.md
• docs/status.md
• ops/AUTONOMOUS_RUN.md
• ops/ROADMAP.md
• release-artifacts/latest/SHA256SUMS
• release-artifacts/latest/abi-checksums.json
• release-artifacts/latest/release-artifact-manifest.json
• release-artifacts/latest/release-checksums.json
• release-artifacts/latest/release-manifest.json
• release-artifacts/latest/source-verification-inputs.json
• smart-contracts/StreamCore.sol
• smart-contracts/StreamMetadataRenderer.sol
• test/README.md
• test/StreamCoreCustomErrors.t.sol
• test/StreamMetadataUtf8.t.sol

---

📝 Walkthrough

Walkthrough

This PR implements production UTF-8 validation for StreamCore metadata inputs by consolidating validation logic into the linked StreamMetadataRenderer library, recovering sufficient bytecode headroom to fit UTF-8 enforcement within the EIP-170 size limit while maintaining size-before-UTF-8 error ordering across all metadata entry points and tests.

Changes

StreamCore Production UTF-8 Enforcement

Layer / File(s)	Summary
Renderer validation helper library smart-contracts/StreamMetadataRenderer.sol	Adds new error types (MetadataFieldTooLarge, MetadataFieldInvalidUTF8, UnsafeMetadataURI, UnsafeRawAttributes) and public validation helpers: onchainTokenURIWithLimit (with size enforcement), requireValidUtf8Bytes, requireValidUtf8ContentUri, requireValidUtf8ScriptUri, requireValidCollectionUris, requireValidUtf8RawAttributes, requireValidUtf8ByteChunks, plus guard functions requireContractMarker and requireNotPaused for contract marker/pause checks via inline assembly.
StreamCore refactoring and UTF-8 error smart-contracts/StreamCore.sol	Introduces MetadataFieldInvalidUTF8(bytes32 field) error and refactors all metadata validation callsites to use StreamMetadataRenderer helpers: addRandomizer and updateContracts use requireContractMarker; updateCollectionInfo uses requireValidUtf8ContentUri; updateImagesAndAttributes uses requireValidUtf8ContentUri and requireValidUtf8RawAttributes; _onchainTokenURI calls onchainTokenURIWithLimit with explicit size limit; _requireCollectionInfoLimits and _requireMaxBytes delegate to renderer validators, removing internal per-field/per-chunk validation loops.
UTF-8 enforcement and error handling tests test/StreamCoreCustomErrors.t.sol, test/StreamMetadataUtf8.t.sol	Adds testTokenMetadataStateUsesCustomErrorForUnmintedToken to verify TokenNotMinted usage. Extends StreamMetadataUtf8Test with six new tests: valid multibyte UTF-8 acceptance across collection/token/image/attribute updates; invalid UTF-8 rejection for each collection field (creation and incremental); token data UTF-8 variants; image/attribute/token data UTF-8 rejection sequences; and size-before-UTF-8 error ordering verification using field-specific error assertions.
Release notes and metadata documentation CHANGELOG.md, docs/known-blockers.md, docs/metadata.md, docs/status.md, test/README.md	Updates CHANGELOG.md with production UTF-8 enforcement scope and implementation approach (renderer library consolidation, TokenNotMinted() adoption). Removes references to size-gating in issue #125 from docs. Updates runtime size figures (24,160 bytes) and EIP-170 headroom (416 bytes). Clarifies that StreamCore now applies strict UTF-8 policy to collection fields, script chunks, token data, token image URIs, and raw attributes while preserving error-ordering rules.
Operational logs and roadmap updates ops/AUTONOMOUS_RUN.md, ops/ROADMAP.md	Advances Queue Item 65 (PR #126 merged) and tracks Queue Item 66 (Core UTF-8, PR #127) in the autonomous worklog. Updates roadmap P1-SIZE-001/P1-META-006 descriptions to document recovered bytecode headroom, UTF-8 enforcement enabling, updated measurements (24,160 bytes runtime, 416-byte headroom), and remaining render-safety sandboxing work. Refreshes decision log with validation and PR opening timestamps.
Deployment manifests and artifact checksums deployments/address-books/*, deployments/examples/*, release-artifacts/latest/*	Updates deployment address books and example manifests with new DependencyRegistry and StreamCore bytecode/ABI hashes. Refreshes all release artifact checksums, source verification inputs (including StreamMetadataRenderer.sol and StreamCore.sol hashes, library linking offsets), and manifest sha256 values to match new compiled artifacts and documentation changes.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant StreamCore
    participant Renderer as StreamMetadataRenderer
    participant Admin as IStreamAdmins
    Caller->>StreamCore: addRandomizer(target)
    StreamCore->>Renderer: requireContractMarker(target, selector, error)
    Caller->>StreamCore: updateCollectionInfo(baseUri)
    StreamCore->>Renderer: requireValidUtf8ContentUri(field, uri, max, allowEmpty)
    Caller->>StreamCore: updateImagesAndAttributes(tokenId, imageUri, rawAttrs)
    StreamCore->>Renderer: requireValidUtf8ContentUri(field, imageUri, max, allowEmpty)
    StreamCore->>Renderer: requireValidUtf8RawAttributes(tokenId, field, rawAttrs, max)
    Caller->>StreamCore: _onchainTokenURI(tokenId, data)
    StreamCore->>Renderer: onchainTokenURIWithLimit(data, field, maxBytes)
    Caller->>StreamCore: _requireMetadataMutationNotPaused()
    StreamCore->>Renderer: requireNotPaused(adminsContract, pauseDomain, errorSelector)
    Renderer->>Admin: isPaused(pauseDomain)
    Admin-->>Renderer: bool
    Renderer-->>StreamCore: revert or return
    StreamCore-->>Caller: revert or continue

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related issues

• #125: Main changes directly implement the acceptance criteria for recovering bytecode headroom and enabling production UTF-8 enforcement for StreamCore metadata fields; PR resolves the issue by consolidating validation into renderer helpers to fit enforcement within EIP-170 limits.

Possibly related PRs

• 6529-Collections/6529Stream#126: Applies parallel UTF-8 enforcement pattern to DependencyRegistry script/provenance writes using the same StreamMetadataRenderer validation utilities that this PR extends into StreamCore metadata paths.
• 6529-Collections/6529Stream#90: Establishes the foundational StreamMetadataRenderer/StreamCore integration points that this PR builds on; the main PR delegates validation through the same renderer library call sites that PR #90 introduced.

Poem

A rabbit hops through metadata streams,
Checking UTF-8 byte sequences, or so it seems.
With helpers consolidated in the renderer's care,
Core bytecode breathes freely—no size despair! 🐰✨

🚥 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 'Enforce Core UTF-8 metadata policy' directly describes the main change: adding strict UTF-8 validation for StreamCore production metadata inputs, which is the central objective of the PR.
Linked Issues check	✅ Passed	The PR addresses all acceptance criteria from issue #125: StreamCore rejects invalid UTF-8 across specified metadata fields, preserves valid UTF-8 acceptance, maintains error ordering (size before UTF-8), achieves the documented 416-byte headroom margin, and updates roadmap/status/release artifacts.
Out of Scope Changes check	✅ Passed	All changes align with PR objectives: smart-contract enforcement additions, linked renderer helper consolidation, bytecode recovery via helper consolidation and TokenNotMinted() introduction, comprehensive test coverage, and systematic documentation/artifact updates reflecting the UTF-8 enforcement and headroom changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/core-utf8-headroom

---

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