Confidential Token Docs

[brozorec]

Summary by CodeRabbit

• Documentation
  • Added a new end-to-end guide covering confidential token user flows, wallet expectations, auditing, recovery, and edge cases.
  • Added a new selective-disclosure guide explaining how users can share transaction details securely and verify proofs against ledger state.
  • Expanded compliance and design docs with clearer explanations of authorization flow, optional policy checks, clawback/freeze behavior, and linked references between documents.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

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: Pro

Run ID: 7aec11ed-e387-44c4-84b2-6b951b0905ae

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

Walkthrough

The PR expands confidential-token documentation with compliance clarifications, a linked user-flows overview, a new end-to-end overview page, and a selective-disclosure specification covering protocol flow, circuit variants, security notes, and implementation guidance.

Changes

Confidential token documentation

Layer / File(s)	Summary
Compliance policy clarifications packages/tokens/src/confidential/docs/COMPLIANCE.md	COMPLIANCE.md expands SAC passthrough, optional policy, and unregistered deposit guidance.
Clawback and auditor roles packages/tokens/src/confidential/docs/COMPLIANCE.md	COMPLIANCE.md adds clawback framing and rewrites the admin and auditor coordination section.
Docs index and overview packages/tokens/src/confidential/docs/DESIGN.md, packages/tokens/src/confidential/docs/OVERVIEW.md	DESIGN.md links the new overview and selective-disclosure pages, and OVERVIEW.md adds the end-to-end confidential token overview.
Selective disclosure protocol packages/tokens/src/confidential/docs/SELECTIVE_DISCLOSURE.md	SELECTIVE_DISCLOSURE.md defines the disclosure model, preliminaries, threat model, proof bundle, verifier flow, and optional on-chain verification.
Disclosure circuits packages/tokens/src/confidential/docs/SELECTIVE_DISCLOSURE.md	SELECTIVE_DISCLOSURE.md defines the D-recipient, D-sender, and D-auditor circuits and their verifier rules.
Balance, aggregate, and notes packages/tokens/src/confidential/docs/SELECTIVE_DISCLOSURE.md	SELECTIVE_DISCLOSURE.md adds D-balance, aggregate disclosures, the read surface, the end-to-end flow, security analysis, out-of-scope items, and implementation notes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• ozgunozerk

Poem

A bunny hops through docs tonight,
With cloaks of proof and carrots bright.
🐇 Selective whispers, clear and neat,
Compliance crunches into treat!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	No description was provided, so the required issue reference, change summary, and checklist items are missing.	Add the template sections: Fixes #, a summary of the docs updates, and the PR checklist with Tests and Documentation.
Title check	❓ Inconclusive	The title is relevant but too generic to identify the main change among the documentation updates.	Use a more specific title that names the core docs change, e.g. "Add confidential token user flows and selective disclosure docs".

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch confidential-token-docs

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 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 `@packages/tokens/src/confidential/docs/COMPLIANCE.md`:
- Around line 119-121: Clarify the unregistered-sender example in COMPLIANCE.md
so it matches the intended behavior of the `ComplianceHooks` flow: the current
text says only the registration-dependent freeze check is skipped, but the
example still omits policy screening for `from`. Update the paragraph to either
explicitly include `storage::check_policy(e, from, &config)` for unregistered
senders that must still be screened, or reword it to state that the example
skips both gates; keep the explanation aligned with the unregistered-deposit
scenario.

In `@packages/tokens/src/confidential/docs/OVERVIEW.md`:
- Around line 123-135: The auditing spec is inconsistent: the decryption flow in
the dual-auditor section requires a per-operation salt from the event, but the
transfer/withdrawal/spender payload tables do not list that field. Update the
payload tables in the confidential auditing overview to include the salt for
each relevant operation/event payload, or remove the salt requirement from the
channel sponge decryption description so both sections match. Keep the wording
aligned with the “real-time auditing” and “Each auditor decrypts…” paragraphs to
make the spec unambiguous.

In `@packages/tokens/src/confidential/docs/SELECTIVE_DISCLOSURE.md`:
- Line 209: Fix the typo in the SELECTIVE_DISCLOSURE documentation by replacing
the incorrect “requestor” wording with “requester” in the request/response
description; update the sentence in the event-anchored facts section so the
terminology is consistent with the surrounding verifier/requester flow.
- Around line 420-423: The threshold constraint label is using the acronym THR,
which is triggering the typo checker and reducing readability. Update the label
in the selective disclosure docs to spell out the full identifier as THRESHOLD
(or otherwise align it with the repository’s accepted terminology) in the
section describing the constraint summary and the U1–U3/aggregate-value flow.
- Line 448: The fenced diagram block is missing a language identifier, which
triggers markdownlint. Update the relevant fenced block in
SELECTIVE_DISCLOSURE.md to include an explicit tag such as text while keeping
the diagram content unchanged; locate the fence in the markdown section near the
selective disclosure diagram and adjust only the fence syntax.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8bf976ea-6165-46c0-bea8-8364ead96143

📥 Commits

Reviewing files that changed from the base of the PR and between 278fbea and 93b3692.

📒 Files selected for processing (4)

• packages/tokens/src/confidential/docs/COMPLIANCE.md
• packages/tokens/src/confidential/docs/DESIGN.md
• packages/tokens/src/confidential/docs/OVERVIEW.md
• packages/tokens/src/confidential/docs/SELECTIVE_DISCLOSURE.md