Skip to content

Expose stale and failed randomness metadata states#131

Merged
punk6529 merged 4 commits into
mainfrom
codex/metadata-randomness-state-display
Jun 12, 2026
Merged

Expose stale and failed randomness metadata states#131
punk6529 merged 4 commits into
mainfrom
codex/metadata-randomness-state-display

Conversation

@punk6529

@punk6529 punk6529 commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Maps lifecycle-aware Stale and FailedPostProcessing requests into public tokenMetadataState, off-chain token URI suffixes, and schema-v1 on-chain JSON while preserving unsupported/missing lifecycle fallback to pending and nonzero-hash override to final.
  • Adds focused golden fixtures/tests for stale, failed, lifecycle lookup fallback, unsupported-lifecycle fallback, and final-hash override behavior.
  • Updates metadata docs, randomness/freeze/redeployment ADRs, status/known-blocker docs, roadmap/run-state traceability, changelog, and regenerated release artifacts.
  • Documents the resulting size-budget debt: StreamCore is EIP-170 compliant at 24,348 runtime bytes with 228 bytes of headroom, below the repo's 384-byte internal release floor.

Tests

  • forge test --match-path test\StreamMetadataGolden.t.sol -vvv
  • forge build --sizes --via-ir --skip test --skip script --force
  • make release-checksums
  • make release-checksums-check
  • make check
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check.ps1
  • forge fmt --check smart-contracts\StreamCore.sol test\StreamMetadataGolden.t.sol
  • git diff --check

Closes #130

Summary by CodeRabbit

  • New Features

    • Token metadata now reports four lifecycle states — pending, stale, failed, final — for clearer randomness/display behavior.
  • Documentation

    • Architecture, ADRs, roadmap, status, and ops docs updated to reflect expanded lifecycle states, display rules, rollout/test guidance, and revised runtime size/headroom/deployability notes.
  • Tests

    • Added lifecycle-aware tests and golden-fixture coverage for pending/stale/failed/final on both off-chain and on-chain schema views.
  • Fixtures

    • New/updated metadata fixtures covering stale and failed URIs and schema-v1 on-chain payloads.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

coderabbitai Bot commented Jun 12, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0ffc133d-9366-471a-a239-6bc449258fac

📥 Commits

Reviewing files that changed from the base of the PR and between 226b716 and fe618b1.

📒 Files selected for processing (18)
  • 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/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
  • test/README.md
  • test/StreamMetadataGolden.t.sol
✅ Files skipped from review due to trivial changes (9)
  • deployments/examples/anvil-6529stream-v0.1.0-001.json
  • release-artifacts/latest/abi-checksums.json
  • release-artifacts/latest/release-checksums.json
  • deployments/examples/anvil-6529stream-v0.1.0-001-broadcast.json
  • CHANGELOG.md
  • release-artifacts/latest/SHA256SUMS
  • ops/AUTONOMOUS_RUN.md
  • docs/known-blockers.md
  • release-artifacts/latest/source-verification-inputs.json
🚧 Files skipped from review as they are similar to previous changes (7)
  • deployments/address-books/anvil-6529stream-v0.1.0-001.json
  • deployments/address-books/anvil-6529stream-v0.1.0-001-broadcast.json
  • test/README.md
  • test/StreamMetadataGolden.t.sol
  • release-artifacts/latest/release-manifest.json
  • smart-contracts/StreamCore.sol
  • ops/ROADMAP.md

📝 Walkthrough

Walkthrough

Adds lifecycle-aware metadata states (pending, stale, failed, final) by extending StreamCore to query randomizer lifecycle contracts, mapping lifecycle request states to token display states; introduces a lifecycle mock and golden-fixture tests; and updates ADRs, docs, release manifests, and checksums.

Changes

Lifecycle-Aware Metadata State Implementation

Layer / File(s) Summary
Core Metadata Lifecycle State Detection
smart-contracts/StreamCore.sol
StreamCore adds stale and failed constants; tokenURI computes token-specific pending state via _pendingTokenMetadataState; tokenMetadataState returns final or maps lifecycle request states (via staticcall) to stale/failed/pending; _onchainTokenURI now accepts a caller-provided metadataState.
Lifecycle-Aware Test Mock and Core Tests
test/StreamMetadataGolden.t.sol
Adds MetadataLifecycleRandomizer mock implementing IRandomizer and IRandomizerLifecycle with configurable request state and revert toggle; tests assert stale/failed views, fallback-to-pending on lookup revert or unsupported lifecycle, and finalizeToken override behavior.
Golden-Fixture Tests and Helpers
test/StreamMetadataGolden.t.sol, test/fixtures/metadata/*
Golden-fixture tests validate off-chain tokenURI and on-chain schema-v1 JSON outputs for stale and failed lifecycles; includes _deployWithLifecycleRandomizer() helper and new fixtures (offchain-stale, offchain-failed, onchain-stale-schema-v1, onchain-failed-schema-v1).
ADR and Metadata Specification Updates
docs/adr/0005-randomness.md, docs/adr/0006-metadata-freeze.md, docs/adr/0007-upgrade-redeployment.md
ADRs updated to require explicit on-chain pending/stale/failed/final semantics, expand implementation checklist, tests, and migration steps.
Metadata Behavior Documentation
docs/metadata.md
Documents off-chain stale/failed URI endpoints, expands on-chain metadata_state enumeration to pending/stale/failed/final, clarifies tokenMetadataState lifecycle lookup and final-hash override, and updates golden-fixture lists.
Known Blockers, Status, Roadmap, and Ops
docs/known-blockers.md, docs/status.md, ops/ROADMAP.md, ops/AUTONOMOUS_RUN.md
Updates blockers, Gate A status text, roadmap verification baselines, and autonomous-run logs; records revised StreamCore runtime/headroom figures and expanded lifecycle coverage.
Test README and Sizing Docs
test/README.md, CHANGELOG.md
Expands StreamMetadataGolden characterization notes and CHANGELOG Unreleased entry; updates recorded StreamCore runtime bytes (24,348) and EIP-170 headroom (228) while noting release-floor implications.
Release Artifact and Deployment Refresh
deployments/*/*.json, release-artifacts/latest/*, release-manifest.json, release-artifacts/latest/source-verification-inputs.json
Checksum and manifest entries updated to reflect regenerated artifacts, new StreamCore bytecode hashes, and adjusted library-linking offsets.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

Possibly related PRs

"I nibble on bytes and hashes light,
Stale and failed now spring to sight,
Fixtures lined up, tests all run,
Metadata dance — the rabbit's fun! 🐇✨"

🚥 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 PR title 'Expose stale and failed randomness metadata states' directly and clearly describes the main change: adding support for stale and failed metadata states to the randomness lifecycle system.
Linked Issues check ✅ Passed The PR implementation meets all acceptance criteria from issue #130: tokenMetadataState returns pending/stale/failed/final; stale/failed URIs and JSON metadata_state are correct; final requires nonzero hash; unsupported lifecycle falls back to pending; golden fixtures and tests added; make check passes.
Out of Scope Changes check ✅ Passed All changes are within scope of issue #130: core metadata state logic, test coverage, documentation updates, deployment artifacts, and roadmap/autonomy tracking are all necessary to fulfill the feature and acceptance criteria.
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/metadata-randomness-state-display

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

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 12, 2026

Copy link
Copy Markdown
✅ 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.

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

Head moved only to persist the prior review request in ops/AUTONOMOUS_RUN.md; please review the latest head.

@coderabbitai

coderabbitai Bot commented Jun 12, 2026

Copy link
Copy Markdown

@punk6529 Triggering a review of the latest head now.

✅ 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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/status.md (1)

241-247: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify that freeze rejects stale and failed live tokens too.

ADR 0006 treats live Stale and FailedPostProcessing tokens as non-freeze-eligible, so this summary shouldn’t read as if only pending blocks freeze.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/status.md` around lines 241 - 247, Update the status summary text to
explicitly state that freeze excludes live tokens in the Stale and
FailedPostProcessing states as well as pending; reference ADR 0006 and change
any phrasing that implies only "pending" blocks freeze to something like "freeze
rejects pending, Stale, and FailedPostProcessing live tokens" so readers
understand all non-freeze-eligible live token states are covered.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ops/AUTONOMOUS_RUN.md`:
- Around line 35-40: Update the run-state to reference the actual open PR:
replace the "Active PR" value currently set to `TBD` with `#131` and likewise
update the "Active PR branch" / repository-state table entry if needed to
reflect `codex/metadata-randomness-state-display` → PR `#131`; also edit the Queue
Item 68 worklog to record PR `#131` (apply the same change to entries covering PRs
129-135 where "TBD" appears) so the handoff is self-contained and consistent.

In `@smart-contracts/StreamCore.sol`:
- Around line 820-848: In _pendingTokenMetadataState, don’t assume the
randomizer supports the lifecycle API: first staticcall the
collectionAdditionalData[collectionId].randomizerContract for
IRandomizerLifecycle.supportsRandomizerLifecycle and only proceed to call
randomnessRequestStateForToken (the current selector/assembly block) if that
supports call returns true; otherwise immediately return
_METADATA_STATE_PENDING. Ensure you use the supportsRandomizerLifecycle
selector/result to gate the existing assembly staticcall and state checks so a
contract that exposes randomnessRequestStateForToken but returns false from
supportsRandomizerLifecycle falls back to pending.

---

Outside diff comments:
In `@docs/status.md`:
- Around line 241-247: Update the status summary text to explicitly state that
freeze excludes live tokens in the Stale and FailedPostProcessing states as well
as pending; reference ADR 0006 and change any phrasing that implies only
"pending" blocks freeze to something like "freeze rejects pending, Stale, and
FailedPostProcessing live tokens" so readers understand all non-freeze-eligible
live token states are covered.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f7618779-cfc4-48f1-b860-dbf3ab0da60b

📥 Commits

Reviewing files that changed from the base of the PR and between 7ccc771 and 5c2852f.

📒 Files selected for processing (26)
  • 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/adr/0005-randomness.md
  • docs/adr/0006-metadata-freeze.md
  • docs/adr/0007-upgrade-redeployment.md
  • 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
  • test/README.md
  • test/StreamMetadataGolden.t.sol
  • test/fixtures/metadata/offchain-failed-token-uri.txt
  • test/fixtures/metadata/offchain-stale-token-uri.txt
  • test/fixtures/metadata/onchain-failed-schema-v1-token-uri.txt
  • test/fixtures/metadata/onchain-stale-schema-v1-token-uri.txt

Comment thread ops/AUTONOMOUS_RUN.md Outdated
Comment thread smart-contracts/StreamCore.sol

Copy link
Copy Markdown
Contributor Author

Addressed CodeRabbit review:

  • Gated stale/failed state lookup on supportsRandomizerLifecycle() so selector-compatible randomizers that explicitly report unsupported fall back to pending.
  • Added regression coverage for unsupported lifecycle fallback.
  • Clarified ADR 0006 freeze eligibility docs for pending/stale/failed live tokens.
  • Refreshed size docs/artifacts; StreamCore is now 24,348 bytes with 228 bytes of EIP-170 headroom.

Validation:

  • forge test --match-path test\StreamMetadataGolden.t.sol -vvv
  • forge build --sizes --via-ir --skip test --skip script --force
  • make release-checksums
  • make release-checksums-check
  • make check
  • powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check.ps1
  • forge fmt --check smart-contracts\StreamCore.sol test\StreamMetadataGolden.t.sol
  • git diff --check

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 12, 2026

Copy link
Copy Markdown

@punk6529 Thanks for the detailed summary — the supportsRandomizerLifecycle() gate is a solid hardening step, and the additional regression coverage for the unsupported-lifecycle fallback path is exactly the right way to lock that in. Triggering a review of the latest head now.

🐇 ✅

✅ 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.

@coderabbitai

coderabbitai Bot commented Jun 12, 2026

Copy link
Copy Markdown

@punk6529 Thanks for the thorough follow-up. The supportsRandomizerLifecycle() guard is the right defensive layer — it ensures that any randomizer implementing the selector but returning false cleanly falls back to pending rather than surfacing an unexpected state. The unsupported-lifecycle regression test is exactly the right coverage to lock that path in.

A few notes on the updates:

  • Size delta: 24,319 → 24,348 bytes (+29 bytes) with headroom narrowing from 257 → 228 bytes — still EIP-170 compliant and within the 384-byte release floor, but worth flagging as the size budget continues to tighten.
  • ADR 0006 clarification: Good to have freeze eligibility explicitly scoped to final tokens only, keeping pending/stale/failed tokens outside the freeze path.
  • Validation suite: The full checklist (forge test, build --sizes, checksums, make check, fmt --check, git diff --check) is solid evidence the state is self-consistent.

Triggering a review of the latest head now.

🐇 ✅

✅ 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose stale and failed randomness metadata states

1 participant