---
name: design-review
description: Review Canton design documents and architecture proposals against an incrementally maintained checklist covering clarity, Canton terminology, correctness, security, operability, upgradeability, and future compatibility. Use when evaluating a Canton proposal and producing actionable review comments.
---

# Design Review

Review the complete design against every checklist item. Report only material findings. For each finding, identify the affected passage, explain the problem and its impact, and suggest a precise correction.

1. **Clarity and brevity.** Make every sentence and paragraph express a clear point in direct language. Flag verbosity, convoluted phrasing, vague abstractions, and passages whose purpose is difficult to identify.
2. **Purpose and relevance.** Ensure every section contributes to the proposal's decision or design. Remove redundant material, low-value comparisons, and tangents such as competitive positioning when they do not affect the architecture.
3. **Scope framing.** State what will be delivered, what will not, and why. Do not frame simplicity or extensibility in a way that can be read as avoiding necessary work.
4. **Information order.** Introduce load-bearing decisions, constraints, trust assumptions, and limitations before sections that depend on them. Do not postpone information that the reader needs to understand earlier claims.
5. **Definitions and acronyms.** Define Canton-specific concepts, project-specific labels, acronyms, and referenced symbols before first use. Expand acronyms such as Smart Contract Upgrade (SCU), and explain unfamiliar choices or APIs rather than assuming recognition.
6. **Official Canton terminology.** Use the terminology from authoritative Canton documentation. In particular, distinguish Canton consensus from Daml/Daml-LF execution, and avoid invented or imprecise descriptions when an established term exists.
7. **Concrete Canton concepts.** Prefer precise definitions over abstract analogies. Describe a Canton contract as an instance of a template with state and business logic whose actions are authorized by parties.
8. **Parties versus infrastructure.** Keep parties, accounts, participant or validator nodes, synchronizers, signatories, observers, and controllers conceptually separate. Parties authorize transactions; nodes host parties, vet packages, and participate in validation. Do not attribute a party's decisions or authority to its hosting node.
9. **Role names.** Name application roles by their actual scope. Avoid names such as `CANTON_ADMIN` or `CANTON_OPERATOR` when the role is really an application, venue, asset, or protocol administrator, because Canton already assigns specific meanings to platform roles.
10. **Consistency sweep.** When terminology or a technical claim is corrected, inspect the entire document for every occurrence and make the correction consistently.
11. **Data and state flow.** Include a concise diagram when a design has several actors, contracts, authorization steps, or state transitions. The diagram must clarify data ownership, authority, and the order of state changes rather than repeat prose.
12. **Source grounding and maturity.** Verify named templates, choices, interfaces, package names, and behaviors against real code or authoritative documentation. Link or cite the source, and explain maturity markers or namespaces such as `Experimental` instead of leaving their meaning ambiguous.
13. **Necessary specificity.** Do not prescribe a specialized mechanism, such as zero-knowledge verification, when the requirement only calls for a general verification step. Justify the mechanism or use technology-neutral language, and clearly label mocks, examples, and future components.
14. **DAR availability and vetting.** Account for both package upload and package vetting. A required DAR may be uploaded but unvetted, and the same required version must be vetted on the nodes hosting all relevant signatory and observer parties for a transaction to succeed.
15. **DAR failure consequences.** Explain how an incorrect, missing, or unvetted DAR affects every critical flow, including ordinary settlement, lock-and-sweep, recovery, and administrative actions. Treat loss of package availability as a liveness and operability risk even when funds cannot otherwise move.
16. **Authorization semantics.** Distinguish signatory authority from choice controllership and hosting topology. Verify exactly which parties must authorize creation, exercise, archive-and-recreate transitions, and privileged operations; do not assume signatory status alone implies per-operation approval.
17. **Canton-native decentralization.** State what is decentralized, which parties or nodes participate, and what trust or liveness property the topology provides. Prefer Canton-native patterns such as multi-hosted parties when they meet the requirement, and justify custom attestor pools or governance layers against their added complexity.
18. **Threshold configuration.** Prefer configurable `N-of-M` authorization where appropriate so the same mechanism can express `M-of-M`. Evaluate security against the liveness risk of one unavailable approver stalling the system.
19. **Atomic batch semantics.** State that `SettleBatch` is all-or-nothing: one inactive allocation, archived contract, changed backing holding, failed authorization, or other failing leg reverts the entire batch. Do not describe atomicity only as a benefit; analyze its failure modes.
20. **Batch failure blast radius.** Justify the batching strategy and compare throughput gains with correlated failure risk. Consider single-settlement execution, smaller batches, preflight validation, retries, expiry handling, and other ways to prevent one stale item from reverting unrelated work.
21. **Contention and retries.** Identify contracts consumed by concurrent operations, explain where execution serializes, and quantify the likely effect on latency, throughput, and user retries. Analyze how `SettleBatch` changes that contention rather than discussing pool state in isolation.
22. **Stable contract discovery.** Do not persist a `ContractId` across consuming archive-and-recreate transitions when it will become stale. Evaluate contract keys or another current-state lookup mechanism, including uniqueness, authorization, disclosure, and contention implications.
23. **Conservation and state invariants.** Verify every claimed accounting or funding invariant against all creation, settlement, failure, partial, and recovery paths. Check both state deltas and absolute backing, including initial seeding, surplus change, underfunding, and fragmentation.
24. **Smart Contract Upgrade rules.** Distinguish templates, template choices, interface definitions, and interface instances. Template fields and choice arguments may gain compatible optional values; a template may add an interface but must not change or remove an existing one; an interface definition cannot change, although an interface instance's implementation can.
25. **Upgrade-path enforcement.** Do not assume that adding a stricter parallel choice disables a weaker path. Explain how legacy entry points are closed or made safe, and verify that clients cannot bypass new checks by calling an older choice directly.
26. **Cross-synchronizer compatibility.** State that a contract belongs to one synchronizer at a time and that a transaction requires compatible placement. Where useful, reserve an optional synchronizer identifier on appropriate choices, define its default, and reject unsupported values to gain future compatibility without claiming full multi-synchronizer support.
27. **Operational impact of open questions.** For every deferred decision or future extension, explain its present-day consequence, likely implementation cost, migration path, and failure behavior. Replace unsupported claims that a feature will be a simple drop-in with evidence or a clearly labeled assumption.