Opened 11-03-2026 by hrischuk-da, last activity 5mo ago
Proposal file:
Link to the proposal added in this PR (e.g., /proposals/your-proposal-name.md)
Briefly describe the proposal and the value it delivers to the Canton ecosystem (2–3 sentences).
/proposals/(Add anything the Tech & Ops Committee should pay attention to.)
Showing 1 to 10 of 10, oldest first.
could you change file to .md so that it renders as markdown
My apology. I don't know how I missed this. Fixed.
I thought I recalled reading somewhere the idea that it would be possible to enforce an invariant of contract key uniqueness per synchronizer domain. Has this been dropped? This would be an extremely useful invariant to have; in fact, in almost every use case I've thought about where I wished I had contract keys available it's because of that uniqueness constraint.
Without this constraint I think the proposal needs a bit more functionality to be useful. For instance, something like a version of excerciseByKey that allows you to specify an additional constraint or filter mechanism on which contract(s) get executed. Otherwise I don't think there's any safe way for an application to enforce an at-most-one type semantic here.
Uniqueness being guaranteed by synchronizer has never been part of the engineering roadmap for Canton 3.x. Let's explore why.
Synchronizer supported key uniqueness was provided in Canton 2.x because the architecture only allowed a single synchronizer. The single synchronizer made this feasible. The change that makes this infeasible in Canton 3.x is the support for multi-synchronizer dApps which is a core value proposition of Canton Network. Multi-synchronizer support means:
This should highlight that there are coroner and race conditions that make uniqueness infeasible in a multi-synchronizer world. I don't want to bore you with the others ocnditions.
This does not mean that keys cannot be guaranteed to be unique. It is just that uniqueness is not provided out-of-box by the synchronizers. An insight is that uniqueness needs are a requirement of the dApp so the responsibility for providing uniqueness is delegated to the dApp. There are some thoughts on how to do this in the 2.x documentation: Workarounds for Recovering Uniqueness. Also, when we analyzed this we found that many applications can guarantee key uniqueness because they understand the semantics of their schemas which usually have a unique ID that could be used as the key: a Treasury security has a CUSIP (Committee on Uniform Security Identification Procedures), an invoice has a unique invoice number, etc. So, delegating uniqueness to the dApp is not necessarily a burden.
At the moment, we are working with two very large institutions that are familiar with contract keys, having implemented a 2.x dApp and used contract keys extensively. They are alright with delegating key uniqueness to the dApp and each has a different approach to this. Looking into the future, I foresee the ecosystem providing packaged solutions to key uniqueness based on use case.
Note that you can already implement custom Daml logic in the body of your choice to specify additional constraints. For instance, since you have the authority of the maintainers there, you can use lookupByKey to check for invariant (at the transaction level)
choice C : ()
controller p
do
maybeCid <- lookupByKey @T1 (key this)
assert (maybeCid == None)
...
Alternatively, you could implement a non-consuming exercise that uses queryNByKey, filters the results, selects the specific contract to be used, and then calls an exercise on it. One of the 2.x users that are migrating their dApp to 3.x a way to achieve at-most-one type semantics in this fashion so there is validation that this works.
As mentioned, our recommendation is that the dApp enforces uniqueness at the app level:
That is a long explanation but I wanted to let you know that dApp providers are alright with having key uniqueness delegated to them. Let me know if you have any other questions
Given that both fetchNByKey and queryNByKey can retrieve N active contacts with specified key, what shall be the intended behavior of exerciseByKey in the case where N active contracts exist? Is it expectable that it will attempt to exercise the choice on all N instances?
Objective: dApp development can begin before deployment on Dev/Test/MainNet to validate the contract key semantics and tooling.
Estimated Delivery: Month 2 after approval
Deliverables:
Acceptance criteria:
fetchNByKey, exerciseByKey, and queryNByKey.queryNByKey and exerciseByKey.Command type exerciseByKey. This also exercises the Daml engine.| Milestone | Earliest delivery | CC |
|---|---|---|
| Milestone 1: Two dApp's develop with an early release of the Contract Key functionality | Month 2 | 3.875M |
Objective: Contract key is demonstrated to run on MainNet.
Estimated Delivery: Month 6 after approval
Deliverables:
Acceptance criteria:
| Milestone | Earliest delivery | CC |
|---|---|---|
| Milestone 2: Successful upgrade on MainNet and deployment of any dApp that uses contract keys | Month 6 | 3.875M |
Objective: Validate that large and sophisticated dApp development is enabled by contract key functionality.
Estimated Delivery: Month 10 after approval
Acceptance criteria:
| Milestone | Earliest delivery | CC |
|---|---|---|
| Milestone 3: One investment bank application uses Contract Keys and is live on MainNet | Month 10 | 1.5M |
Objective: Validate contract key functionality for multi-synchronizer dApps and that they perform well enough for general use across synchronizers.
Estimated Delivery: Month 12 after approval
Deliverables:
Acceptance criteria:
| Milestone | Earliest delivery | CC |
|---|---|---|
| Milestone 4: Multi-synchronizer contract key optimizations are deployed and used by a dApp on MainNet | Month 12 | 1.9 M |
CIP-0100 Simplifying dApp programming by reintroducing contract keys
Author: Digital Asset
Status: Proposal
Created: 2026-03-05
This proposal is to reintroduce the contract key feature into the Canton Network technology stack. A contract key is a stable identifier that simplifies reasoning, programming with the UTXO contracts, and managing client integrations which are core to the Canton Network Global Synchronizer. Anecdotally, one organization estimated that the contract key feature decreased their dApp development by 30%. Current Canton Network application providers are asking about it. It is either blocking or slowing Canton 2.x applications from moving to the Canton Network. Since contract keys simplify the programming model, it will make it easier for developers to migrate their application from other blockchains. As a side effect, it can result in lower traffic costs by reducing the number of contracts used for bookkeeping in an application.
Adding back contract keys touches almost every piece of the Canton Network technology stack so this is a significant project. The estimated budget is 11,150,000 Canton Coins. The project can start immediately and extends over 12 months.
The UTXO model of Canton Network's Global Synchronizer imposes a bookkeeping burden on applications. Currently, every contract is tracked by an internal contract ID (an opaque, auto-generated identifier). Since contracts are immutable, a single field update to a contract results in a new contract being created with a brand new contract ID and the old contract is archived so the old contract ID is no longer useful. Yet, the Daml business logic, or its clients, need to track a contract as it evolves which means they must perform bookkeeping tasks each time a contract is updated,archived, and recreated. These bookkeeping tasks require additional Daml logic, backend logic, and integration logic.
This proposal reintroduces the contract key feature which was previously available in Daml 2.x. A contract key is a stable identifier that simplifies reasoning and programming with the UTXO contracts that are core to the Canton Network Global Synchronizer. They relieve the bookkeeping burden of tracking contract IDs as the contract evolves: as a contract is updated, via archive and create operations, the currently active contract can easily be referenced via the contract key. The contract key feature simplifies both the Daml business logic developer as well as the client of that Daml business logic (e.g., backend service).
Contract keys will enable Ethereum or Solana developers to more easily develop applications on the Canton Network because the UTXO mental model is simplified. Services that integrate with the ledger will be simpler because they have a stable identifier to program with and that simplicity pays dividends. This implies that contract keys will make it easier to migrate a dApp from another blockchain to the Canton Network.
Contract keys have not yet been included in Canton 3.x because of the launch timelines and the complexity of extending the feature for a public multi-synchronizer network. It is a new feature so it can be introduced without concerns over backwards compatibility.
Following are some proof points of the benefit:
Once contract keys are available, it is expected that larger and more sophisticated applications can be developed faster because the additional complexity of contract ID bookkeeping is eliminated or greatly reduced.
Contract keys are similar in concept to primary or secondary keys in relational databases. Contract keys do not change and can be used to refer to a contract even when the contract ID changes. Technically, the contract key can be an arbitrary serializable expression that does not contain contract IDs.
Contract key support needs to be threaded through the entire CN application stack. Each affected component is briefly discussed next as background for the discussion of the scope and budget. The affected components are:
Of course, other community developed tools can be enhanced to support contract keys but the components just listed are the canonical foundation for Canton Network so they need to be included in the feature's initial release.
A difference between this proposal and the Daml 2.x implementation is that this proposal allows a contract key to refer to zero, one, or several contracts at the same time; Daml 2.x only allows for zero or one contract to be referred to, as well as to test for non-existence of a contract key. In Canton 3.x, allowing a key to refer to one, zero, or several contracts does have the advantage that a contract key can act like a secondary key of a database.
Each affected component is discussed next.
The Daml language and compiler need to reintroduce two keywords: key and maintainer. To define a contract key in a Daml template, you use the key keyword and specify the maintainer.
key expression is a value that identifies the contract (always includes a Party for scoping).maintainer is the party that validates all action on a key to guarantee their consistency. The central task of the maintainer is to verify the keys are retrieved in a consistent order within the transaction. A maintainer must be a signatory.Here’s an example of setting up a contract key for a bank account, to act as a bank account ID:
type AccountKey = (Party, Text)
template Account with
bank : Party
number : Text
owner : Party
balance : Decimal
observers : [Party]
subaccount: optional AccountKey
where
signatory [bank, owner]
observer observers
key (bank, number) : AccountKey
maintainer key._1
The Daml language and the Daml engine is enhanced to allow for the following new APIs:1
fetchNByKey: A client fetches up to N contract IDs with the same keyexerciseByKey: It allows a client application to exercise a choice on an active contract by specifying its contract key instead of its opaque ContractIDqueryNByKey: returns a list of contract IDs, up to a given limit, using a contract key. It has the ability to do an exhaustive query that returns all the known contracts that have the key.All of these new endpoints will honor the privacy rules of Canton.
The visual studio code IDE needs to be enhanced for:
These are table stakes capabilities.
The Command message in CommandService (Submit / SubmitAndWait) will be enhanced to allow you to exercise a choice on a contract identified only by its key — without knowing the current ContractId. The Command type exerciseByKey will be provided. The EventQueryService type GetEventsByNContractKey, (or similar name) for querying by key, will be added as well.
The Canton runtime adapts to contract keys as follows:
All of the privacy rules of Canton are respected.
Daml Script is used for testing Daml logic. To support contract key use in testing, the Daml Script command queryNByKey will be added to the stdlib and handled in the daml-script runner. An exerciseByKey command will also be added.
The Participant Query Store (PQS) provides a SQL API to query the currently active contracts, as well as historical information. It needs to support querying using a contract key.
Daml Shell is a command line tool for navigating historical contract information and is extremely useful at scale for support purposes. It uses PQS as its data source so it also needs to support contract key query and navigation.
The CN Quick Start is the on ramp for new developers so it should highlight the use of contract keys. It will be restructured to make use of contract keys through the entire application stack.
New documentation and sample code is needed to support application development. This will be added.
There are additional engineering tasks that are included in this plan that are cross cutting: adding documentation, performance optimization, an internal security audit, and an external security audit conducted by an independent, reputable Web3 security firm. The two primary aspects of the performance optimization are:
Similar optimizations in the prior version of contract keys proved fruitful.
To reiterate, contract key support is threaded through the entire CN application stack which involves the following components:
Additional actions are added for the performance optimization, internal security audit, and external security audit.
The project is divided into four distinct milestones over a 12-month period with the acceptance criteria specified for each milestone. The Tech & Ops Committee (or the Core Contributor Group) can evaluate the completion of this milestone based on the evidence identified.
Objective: dApp development can begin before deployment on Dev/Test/MainNet to validate the contract key semantics and tooling.
Estimated Delivery: Month 2 after approval
Deliverables:
Acceptance criteria:
fetchNByKey, exerciseByKey, and queryNByKey.queryNByKey and exerciseByKey.Command type exerciseByKey. This also exercises the Daml engine.Objective: Contract key is demonstrated to run on MainNet.
Estimated Delivery: Month 6 after approval
Deliverables:
Acceptance criteria:
Objective: Validate that large and sophisticated dApp development is enabled by contract key functionality.
Estimated Delivery: Month 10 after approval
Acceptance criteria:
Objective: Validate contract key functionality for multi-synchronizer dApps and that they perform well enough for general use across synchronizers.
Estimated Delivery: Month 12 after approval
Deliverables:
Acceptance criteria:
This proposal does not request funding for ongoing operational maintenance. Upon the successful completion of M1, the day-to-day maintenance of the Contract Key feature will transition to the purview of the 2026-Maintenance Grant for Daml Open Source.
The budget for this project is 11,150,000 CC at each milestone. Please note that ordering of the milestones may vary with later milestones occurring earlier than expected based on dApp adoption.
| Milestone | Earliest delivery | CC |
|---|---|---|
| Milestone 1: Two dApp's develop with an early release of the Contract Key functionality | Month 2 | 3.875M |
| Milestone 2: Successful upgrade on MainNet and deployment of any dApp that uses contract keys | Month 6 | 3.875M |
| Milestone 3: One investment bank application uses Contract Keys and is live on MainNet | Month 10 | 1.5M |
| Milestone 4: Multi-synchronizer contract key optimizations are deployed and used by a dApp on MainNet | Month 12 | 1.9 M |
| Total | 11,150,000 |
Volatility Stipulation for delays caused by scope changes:
As this project is expected to complete within 12 months, we propose that requested scope changes by the Committee result in the remaining un-minted milestones be renegotiated to account for any significant USD/CC price volatility.
The Canton Foundation acknowledges that certain technical milestones outlined in this proposal may have been finalized prior to the formal approval of this grant to maintain network development velocity. In instances where a milestone’s "Definition of Done" and associated success criteria have been met and verified prior to the grant’s effective date, the Foundation agrees to authorize retroactive payment for said deliverables. Verification shall be based on the timestamped completion of the specific GitHub Pull Requests, technical documentation, protocol upgrades or adoption metrics referenced in the milestone delivery plan.
To accelerate the adoption of this feature, the Foundation can provide the following support:
These names may adjust based on user experience feedback but the same functionality is implemented. ↩
Rebuilt from the recorded board moves (complete history). get_dev_fund_lifecycle(number) gives the same in the MCP.