Skip to content

docs(reputation): reserve kind 38388 for the issuer keyset event - #61

Open
grunch wants to merge 2 commits into
docs/reputation-bandsfrom
docs/reputation-keyset
Open

grunch wants to merge 2 commits into
docs/reputation-bandsfrom
docs/reputation-keyset

Conversation

@grunch

@grunch grunch commented Sep 12, 2026

Copy link
Copy Markdown
Member

Summary

Phase 0, PR 0.3 of the reputation portability plan (mostro/docs/REPUTATION_PORTABILITY.md, §5.2).

Stacked on #60. Base branch is docs/reputation-bands; review that one first. Both add a SUMMARY.md entry, which is why this is stacked rather than parallel.

New page src/reputation_keyset.md.

  • Kind 38387 reserved — the next free number after disputes (38386), added to the event-kind tables on both order_event.md and overview.md.
  • d = reputation-keyset:<epoch>, with the epoch repeated as its own tag and required to agree. The epoch lives inside d because addressable events replace on (kind, pubkey, d): a fixed d would delete the previous keyset on every rotation and strand tokens from an epoch the destination still accepts.
  • Content: cells (effective cells → compressed points, lowercase hex) and merges (the published raw → effective map from docs(reputation): specify the reputation band grid #60), with the rule that every one of the 36 raw cells is a key of exactly one map.
  • Five acceptance checks a consumer must pass before caching, so a relay cannot substitute a P_cell.
  • Epochs: the UTC calendar year as a protocol constant, current and previous accepted.
  • Immutability within an epoch, with the concrete failure it prevents: recomputing the merge on a restart drops the key of a cell folded away since, and every token minted against that cell stops verifying while its epoch is still live.

Open decision closed

Open decision 4 of the proposal, at the proposal's own default for the epoch length:

Part Value
Keyset event kind 38387
Epoch length and label UTC calendar year, four ASCII digits

The kind number wants your sign-off — it is the first number claimed outside the 38383-38386 block and is expensive to move once an issuer publishes.

Out of scope

Points are described here only as "33-byte compressed SEC1, lowercase hex" because the keyset content needs it. The full canonical encoding table, the token shape and the four actions land in 0.4; the vectors in 0.5.

Checks

  • mdbook build succeeds locally
  • Both event-kind tables updated
  • The bands page now links forward to this one

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jkd49JmWc7twBRrYTgjnR2

A destination verifies a portable-reputation token with the issuer's public
point for the token's cell, and nothing else from the issuer. This is the
event that publishes those points.

- Kind 38387, addressable, `d` = `reputation-keyset:<epoch>`, with the epoch
  repeated as its own tag. The epoch is inside `d` because addressable events
  replace on (kind, pubkey, d): a fixed `d` would delete the previous keyset
  on every rotation and strand tokens from an epoch still being accepted.
- Content carries `cells`, the effective cells and their compressed points,
  and `merges`, the published raw to effective map, so a client reproduces
  the issuer's K-anonymity assignment instead of trusting it.
- The five checks a consumer must pass before caching an event, so a relay or
  a third party cannot substitute a point.
- Epoch is the UTC calendar year, a protocol constant rather than an issuer
  choice, and a destination accepts the current and previous only.
- A keyset is immutable within its epoch, with the failure it prevents spelled
  out: recomputing the merge on a restart would drop the key of a cell folded
  away since, and every token minted against it would stop verifying.

Adds 38387 to the event-kind tables on both pages that carry one.

Reputation portability plan, phase 0, PR 0.3 (mostro
docs/REPUTATION_PORTABILITY.md §5.2).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jkd49JmWc7twBRrYTgjnR2
@coderabbitai

coderabbitai Bot commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (1)
  • develop

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 03c235d2-77be-43cd-848e-0e08de8ba081

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 12, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-12T12:59:25.873240Z 41f8590 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 41f859011d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/reputation_keyset.md
Comment on lines +83 to +85
5. `content` parses into `cells` and `merges`, every key of both is a valid
[cell id](./reputation_bands.md#cell-id), every value of `cells` is a valid
compressed point on secp256k1, and every value of `merges` is a cell id.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Validate merge chains before caching the keyset

The listed acceptance checks allow a keyset whose merges values are syntactically valid cell IDs but form a cycle or terminate at a cell absent from cells. Such an event passes check 5 and may be cached, yet consumers cannot resolve affected raw cells to a verification key; merely terminating the traversal on a cycle does not make the keyset usable. Require the 36-cell exclusive partition stated above and verify that every merge chain is acyclic and ends at a key present in cells before caching.

Useful? React with 👍 / 👎.

38387 is already spoken for: PR #56 reserves it for announcement events. That
PR is open rather than merged, so the row is absent from main and a grep of
this repo does not show it, which is how the collision got here.

The keyset takes the next free slot instead. Nothing else about the event
changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jkd49JmWc7twBRrYTgjnR2
@grunch

grunch commented Sep 12, 2026

Copy link
Copy Markdown
Member Author

Corrected: the keyset event now takes 38388, not 38387.

38387 is already spoken for by #56, which reserves it for announcement events. That PR is open rather than merged, so the row is absent from main and a grep of this repo does not surface it — which is exactly how I walked into the collision. Caught by @grunch on review, not by me.

Pushed as a follow-up commit rather than a rebase, so the review history on this PR stays intact, and merged forward into #62 and #63. No 38387 remains anywhere in the stack.

One thing for whoever merges second. Both #56 and this PR add a row to the event-kind tables in src/order_event.md and src/overview.md, immediately after Disputes. That is a textual conflict, not a semantic one: the numbers no longer clash. Whichever lands second resolves it by keeping both rows in numeric order.

@grunch grunch changed the title docs(reputation): reserve kind 38387 for the issuer keyset event docs(reputation): reserve kind 38388 for the issuer keyset event Sep 12, 2026
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.

1 participant