Proposal: add ISO 20022 ↔ Canton Settlement Adapter

[akameoww]

Development Fund Proposal Submission

Proposal file:
/proposals/proposal-iso-20022-canton-settlement-adapter.md

Summary

This proposal requests funding for the ISO 20022 ↔ Canton Settlement Adapter, an open-source, bidirectional library that lets banks, PSPs, and custodians initiate and reconcile settlement on Canton straight from their existing payment systems, without a core-banking rewrite.

Canton's own documentation states there is no native ISO 20022 capability, and that integrators "must build an intermediary translation layer" themselves. With JPM Coin (Kinexys), DTCC tokenized Treasuries, and Visa (Super Validator) all live in 2026, that layer is the last step missing for institutional adoption. Today it is rebuilt privately by each institution, or it blocks onboarding.

We build it once, as a public good: standardized ISO 20022 messages (pacs.008, pacs.002, camt.05x) translate into CIP-56 token transfers and atomic DvP via the CIP-0103 dApp / JSON Ledger API, and back again.

In short:

• The institutional pipeline already speaks ISO 20022; Canton speaks CIP-56 / CIP-0103.
• This proposal delivers the reusable mapping layer plus a public conformance suite that bridges the two, instead of many fragmented private integrations.

It is not a message bus and not a new rail. Translation happens at the edge; Canton's private, atomically-composable settlement stays native.

What this delivers

• a published, versioned mapping standard (pacs.008 → CIP-56 transfer/DvP) plus a public golden-vector conformance suite;
• a working PoC at Milestone 1: a real pacs.008 drives a CIP-56 transfer on DevNet and returns a pacs.002 (open-source, CI-green, recorded demo);
• the reverse path: pacs.002 status and camt.05x statements generated from on-ledger events, with idempotent reconciliation keyed by MsgId/EndToEndId;
• atomic DvP via CIP-56 allocations (securities-vs-cash);
• a reusable JVM library plus CIP-0103 integration layer and a complete reference integration;
• security and data handling (no PII on-ledger, schema validation, signing via the institution's CIP-0103 provider, full audit trail);
• a clear party / instrument resolution model (IBAN/BIC/LEI → Canton party; currency → CIP-56 InstrumentId).

Disclosed Contracts and createdEventBlob Handling

The adapter does not fake or manually serialize createdEventBlob.

It reuses the existing token-standard registry choice-context mechanism: it queries the registry off-ledger API (e.g. POST /registry/transfer-instruction/v1/transfer-factory) for factoryId, choiceContextData, and disclosedContracts. Where a createdEventBlob has to be (re)fetched, it is read from the participant via the JSON Ledger API active-contracts query with includeCreatedEventBlob=true (or equivalent gRPC), cached by contract id, and attached to the submission.

The transfer is then exercised through the normal CIP-0103 / JSON Ledger API command path, the same way a compliant wallet does. No protocol or CIP-56/CIP-0112 changes are required.

Checklist

• Proposal file added under /proposals/
• Milestones and funding amounts defined (1,400,000 CC across 4 milestones, ~6 months)
• Acceptance criteria included (adoption- and demonstration-based)
• Alignment with Canton priorities described

Notes for Reviewers

This proposal is intentionally narrow and single-objective: v1 covers pacs.008 / pacs.002 / camt.05x plus DvP only; all other ISO 20022 message types are explicitly deferred / out of scope.

The main points:

• No competing work, real gap. There is no native ISO 20022 layer on Canton, and no other proposal builds one. Proposal: Institutional FX Settlement Infrastructure for Asia.md #139 (FX Settlement) only claims compatibility. Canton's own docs say every integrator must build this layer themselves, so we build it once, as a public good, instead of many fragmented private versions.
• Force-multiplier, zero protocol risk. Every external payment expressed as a CIP-56 transfer makes the already-funded CIP-56 / CIP-0103 standards more valuable. It is purely additive: no protocol, ledger-contract, or CIP-56/CIP-0112 changes. It reuses the standard as-is and translates only at the edge, so Canton stays the private, composable settlement layer rather than a message bus.
• Plays to Canton's unique edge. Atomic, privacy-preserving DvP is exactly what legacy ISO 20022 rails cannot do, so this routes real institutional flows (the pipeline already runs on ISO 20022) onto Canton's core strength.
• De-risked, not a paper idea. A real pacs.008 → CIP-56 transfer → pacs.002 lands on DevNet at Milestone 1, and a public conformance suite makes "adopted" objective rather than aspirational.

[github-actions]

SIG labels auto-detected and applied: canton-apis

If this is incorrect, you can ask the reviewers to update the labels.

[github-actions]

Champion identified Canton Foundation

The committee will verify this champion during review.

[Denend]

1. How does the adapter resolve an ISO 20022 debtor/creditor (IBAN / BIC / LEI) to a Canton party ID - configured directory?

2. Ccy=USD is a currency, not a tokenized instrument (USDC, USDP, JPM, DTCC...). How does the adapter pick which CIP-56 InstrumentId to settle against?

[akameoww]

@Denend

Thanks for the feedback.

1 - Canton party IDs aren't derivable from banking identifiers and there's no global directory, so the adapter doesn't try to infer anything. Resolution is explicit: a configured, institution-owned directory that maps IBAN/BIC/LEI to a Canton party id and its hosting participant. That data isn't something new to build, it's the bank's existing SSI/counterparty information expressed as signed config, and each institution only needs to know its own counterparties. If a counterparty can't be matched cleanly, the adapter rejects the message with a pacs.002 reason code instead of guessing. We can also resolve through CNS when a counterparty has published its mapping there, and through vLEI down the line, but neither is needed for v1.

2 - Ccy=USD is a currency, not a token, so we never assume USD means USDC. CIP-56 already makes the instrument explicit: an InstrumentId is { admin: registry party, id }, so "which USD" really means "which registry." The token is chosen explicitly, in priority order: from the settlement agreement or account between the two parties (again the SSI model, e.g. A and B agree to settle USD in JPM Coin), from an explicit instrument reference in the message (a structured or Prtry field), or from a per-deployment default when only one instrument exists for that currency. If a currency could map to more than one instrument and nothing makes it clear, we reject rather than settle in the wrong token.

For transparency I've also updated the proposal to spell this out directly: the Party Resolution directory (with the fail-closed reject behaviour), the explicit instrument-resolution rules, and a note on ISO 4217 coverage (we only settle currencies that have a configured CIP-56 instrument; everything else is a clean reject).

[Denend]

1. ISO 20022 pacs.008 SttlmMtd supports INDA, INGA, CLRG, COVE. Canton's transfer-factory exposes only {self, direct, offer} - natural-maps to INDA/INGA only. COVE and CLRG require multi-hop chains. Is v1 limited to INDA/INGA, with COVE and CLRG deferred?

Ref: https://github.com/hyperledger-labs/splice/blob/main/token-standard/splice-api-token-transfer-instruction-v1/openapi/transfer-instruction-v1.yaml

[Denend]

2. Q2. CIP-56 Allocation_ExecuteTransfer is controlled jointly by [executor, sender, receiver]. ISO 20022 pacs.008 only carries debtor and creditor agents - no executor role. Who fills the executor in v1, and how is its signature collected per pacs.008?

Ref: https://github.com/hyperledger-labs/splice/blob/main/token-standard/splice-api-token-allocation-v1/daml/Splice/Api/Token/AllocationV1.daml

[akameoww]

1. Yes. v1 is scoped to INDA and INGA, with COVE and CLRG deferred.

The reason is that ISO 20022 SttlmMtd does not map 1:1 to Canton transfer-factory kinds like self, direct, or offer. In this adapter, SttlmMtd is used to decide which settlement topology we can safely build.

INDA and INGA are the bilateral cases: settlement happens on one agent’s books, so they fit the v1 path cleanly. The adapter creates a single TransferFactory transfer. Depending on the registry rules, that transfer may complete directly or require receiver acceptance through the offer/accept flow.

COVE is a different shape. The pacs.008 carries the customer credit transfer, but the actual interbank funds settlement relies on a separate pacs.009 COV cover leg through the correspondent chain. That makes it a multi-message, multi-hop workflow rather than a single transfer.

CLRG is also out of scope for v1. It routes settlement through a clearing system / market infrastructure, which means modelling a clearing intermediary. That belongs in a later milestone, not in the first bilateral transfer implementation.

So v1 supports INDA and INGA only. If a pacs.008 carries an unsupported SttlmMtd, the adapter rejects it with pacs.002 RJCT and an explicit unsupported-settlement-method reason. We do not try to downgrade COVE or CLRG into a bilateral transfer.

2. For the v1 INDA / INGA path, there is no executor.

A single-leg credit transfer does not use the Allocation model. It uses a TransferFactory transfer instead. The sender authorises the transfer instruction, and if the registry requires receiver acceptance, the receiver authorises the accept step separately.

The [executor, sender, receiver] joint-control model applies only to the Allocation / DvP flow. That is a later two-leg milestone, not part of the v1 single-leg pacs.008 path.

When the Allocation / DvP path is added, the executor will be a configured settlement-coordinator party: either the adapter/operator party or a settlement agent agreed between the institutions. It is a deployment or bilateral-configuration role, not a field taken from the ISO message.

So the executor is not derived from pacs.008, and no executor signature is collected from pacs.008 in v1. In the future Allocation/DvP flow, the executor will sign as the configured coordinator party through the adapter’s ledger signing setup.

[daravep]

Thank you for your proposal. I do think that integration work into existing systems is going to be key for the network and as such I welcome your proposal.

I left a few comments for your consideration.

[daravep]

I am a bit surprised to read CIP-103 as the dApp standard is specifically geared towards end-user experience and wallet discovery, whereas I would expect this adaptor to be an integration process.

[akameoww]

Agreed. This is an unattended back-office integration, so it runs on the JSON/gRPC Ledger API directly, plus the token-standard registry off-ledger APIs, with signing through the institution's own provider. CIP-0103 only enters if someone wants to route signing through a dApp-API wallet, which is optional — not the integration path. Tightened in the proposal.

[daravep]

Note that ISO20022 has been integrated for some commercial projects in the past. The code is not OSS but the integration spanned a very large scope of the ISO20022 messages. I'd be happy to share some insights in a bilateral convo.

[akameoww]

That'd be really useful, so yes, let's talk privately

[daravep]

I wouldn't build a declarative mapping engine. Effectively "configuration files" are also code, just built in a custom syntax. You might get more flexibility at less complexity if you provide these mapping capabilities as an extensible interface of the adaptor code itself. I'd rather code these mappings up as a JVM function.

[akameoww]

Yeah, I switched to a typed mapper interface in the adapter, integrators implement a JVM function with real types and tests, and extend by implementing the interface. Only the tabular lookups stay as data: the party directory and the currency - InstrumentId map. Updated in the spec.

[daravep]

I think you should update this to CIP-112 that introduces better account structures.

[akameoww]

Yeah, I'd already been leaning this way on V2, had been discussing it with @meiersi-da too. The V2 Account fits the ISO block much better than a flat party: owner is the Dbtr/Cdtr, provider is the account-servicing agent (the DbtrAgt/CdtrAgt BIC), and id is the IBAN. I've pointed the mapping at a V2 Account; v1 assets stay party-level (basicAccount) for now, so it's an upgrade rather than a new dependency.

[daravep]

Do you have the non-happy path on the radar? I would assume so but I think you should maintain a list of possible failures and provide insights on how these will be handled (e.g. mismatch between party in the party directory and on-ledger topology state, unavailable counter participants, timeouts, etc.).

[akameoww]

Yes, it's in the spec as a maintained list. Each failure resolves to a deterministic pacs.002 with an ISO reason code; transient cases hold in PDNG with bounded retry and reject only on expiry.

Failure	Handling - pacs.002
Party directory entry mismatches on-ledger topology (party absent / not hosted as expected)	reject BE06 (AC04 if account closed)
Counterparty participant unavailable / settlement doesn't complete	PDNG, bounded retry, then RJCT ED05
Receiver doesn't accept before executeBefore (timeout)	PDNG, then RJCT on expiry
Insufficient holdings	RJCT AM04
Currency with no configured CIP-56 instrument	RJCT AM03
Unsupported SttlmMtd (COVE/CLRG)	RJCT NARR
Registry / createdEventBlob fetch failure	refetch / retry; persistent - RJCT ED05
Transient ledger contention	retry preserving change ID; permanent - RJCT ED05
Malformed message (XSD / CBPR+ / HVPS+)	RJCT FF01 before any ledger action
Duplicate MsgId/EndToEndId	no second settlement; original status returned (DU01/DU04 if a true duplicate)
DvP single-leg failure	both-or-neither, never partial; single combined RJCT ED05

Idempotency (MsgId/EndToEndId - ledger change ID) prevents double-settlement, and atomic settlement means a failed submission leaves nothing settled - always a pacs.002 reject, never a pacs.004 return.

[akameoww]

Thank you for your proposal. I do think that integration work into existing systems is going to be key for the network and as such I welcome your proposal.

I left a few comments for your consideration.

Thanks @daravep , appreciate the review. Replied inline, and I've updated the proposal on the back of it, including the Token Standard V2 (CIP-0112) piece, which I'd discussed with @meiersi-da, so it's now reflected as the forward path.

[bame-da]

@akameoww Do you have a specific design partner or user zero lined up for this? In my experience, such components end up with a fair amount of customisation and special requirements that emerge in the context of the kinds of projects where ISO 20022/FIX compatibility is an issue. So to give this the highest potential for success, either this has to be developed in the context of a specific project, or with specific design partners in hand, or be structured to be highly customizable - e.g. as sample code or just as a codec/library that is flexible to integrate.

[akameoww]

@akameoww Do you have a specific design partner or user zero lined up for this? In my experience, such components end up with a fair amount of customisation and special requirements that emerge in the context of the kinds of projects where ISO 20022/FIX compatibility is an issue. So to give this the highest potential for success, either this has to be developed in the context of a specific project, or with specific design partners in hand, or be structured to be highly customizable - e.g. as sample code or just as a codec/library that is flexible to integrate.

Good point, and it matches what we've seen, ISO 20022 integrations always pick up institution-specific quirks. That's exactly why we built the adapter as a flexible library, not a turnkey product, so the mapping engine is an extensible typed interface (institutions override by implementing it, not forking the core), it ships as an embeddable library plus a reference integration to reuse as-is, and the public conformance vectors let anyone verify a customized deployment is still spec-correct. So the customizability route you describe is already baked in, that part's settled

[drewharding-da]

I was part of a team that implemented a component that did almost exactly this for both ISO and FIX messaging, and in the end I would caution against it. In the course of working on it we found quite a few negative outcomes that would make me suggest that this isn't the best solution for addressing legacy integration to a distributed ledger. Despite the fact we successfully managed to build a reusable ISO adapter driven entirely by XSDs and configuration, we decided to leave it with the one implementation and not look to carry it forward into future solutions. Our findings were:

• It's difficult to do this in a way that trades off complexity against a specific implementation. Real world examples of ISO / FIX messages generally end up customised in some fashion. Providing a library that supports this kind of flexibility introduces this complexity in every solution, and reduces the value of a common library. You either end up with something that's not reusable or something that becomes more complicated than it needs to be.
• It's a technical "square peg into a round hole" problem. Recreating existing traditional messaging flows in a distributed paradigm results in poor distributed system design and reduces the technical value of using a ledger. Design decisions end up making it easy for issues such as performance and contention to become baked into the system architecture and then accordingly much harder to solve for.
• Business workflows don't get the attention they need to optimise and take advantage of the new capabilities on offer, and as a result don't take on the advantages of Canton. The opportunity to redesign business workflows within the new paradigm is lost and the business direction becomes more "lift and shift". This ironically decreases the chance of overall success of the solution even if implemented successfully technically, and results in a loss of value to the network.
• Inexperienced engineers that are new to ledger technology don't learn to think in a distributed context and instead try to simply plug components together. Patterns like CQRS and event sourcing, as well as design decisions taking into account CAP theorem trade-offs aren't considered. Accidental complexity increases as teams make assumptions of a new unfamiliar technology that don't hold. and solutions start to treat the ledger like a large database.

Take it for what it's worth, but my experience is all of the above are very hard to mitigate against because they are natural outcomes of the way people think about the component as opposed to something that can be solved by a smarter implementation.

[akameoww]

I was part of a team that implemented a component that did almost exactly this for both ISO and FIX messaging, and in the end I would caution against it. In the course of working on it we found quite a few negative outcomes that would make me suggest that this isn't the best solution for addressing legacy integration to a distributed ledger. Despite the fact we successfully managed to build a reusable ISO adapter driven entirely by XSDs and configuration, we decided to leave it with the one implementation and not look to carry it forward into future solutions. Our findings were:

• It's difficult to do this in a way that trades off complexity against a specific implementation. Real world examples of ISO / FIX messages generally end up customised in some fashion. Providing a library that supports this kind of flexibility introduces this complexity in every solution, and reduces the value of a common library. You either end up with something that's not reusable or something that becomes more complicated than it needs to be.
• It's a technical "square peg into a round hole" problem. Recreating existing traditional messaging flows in a distributed paradigm results in poor distributed system design and reduces the technical value of using a ledger. Design decisions end up making it easy for issues such as performance and contention to become baked into the system architecture and then accordingly much harder to solve for.
• Business workflows don't get the attention they need to optimise and take advantage of the new capabilities on offer, and as a result don't take on the advantages of Canton. The opportunity to redesign business workflows within the new paradigm is lost and the business direction becomes more "lift and shift". This ironically decreases the chance of overall success of the solution even if implemented successfully technically, and results in a loss of value to the network.
• Inexperienced engineers that are new to ledger technology don't learn to think in a distributed context and instead try to simply plug components together. Patterns like CQRS and event sourcing, as well as design decisions taking into account CAP theorem trade-offs aren't considered. Accidental complexity increases as teams make assumptions of a new unfamiliar technology that don't hold. and solutions start to treat the ledger like a large database.

Take it for what it's worth, but my experience is all of the above are very hard to mitigate against because they are natural outcomes of the way people think about the component as opposed to something that can be solved by a smarter implementation.

Thank you, this is genuinely valuable feedback, especially coming from someone who's built this at scale.

I'll be straight about where it leaves the proposal. The strongest version of your point is that a universal, build-it-for-the-future ISO 20022 adapter is the wrong unit of work. Without a concrete client it rots, and at worst it turns the ledger into a message gateway and gives an institution permission to never move into a composable model. That's a fair correction to how the proposal currently reads, and I agree with it.

A few things I'd keep, because I think they line up with your own conclusions:

• Generic and stateless, with all interpretation and state in Daml. The adapter should only encode an ingress message into a command and decode a transaction-tree event into an outbound message, nothing more. The failure mode you name, business logic duplicated across adapters and operators forced to upgrade in lockstep, is exactly what that boundary is meant to prevent. If the current write-up reads like the mapping engine owns business logic, that's a wording problem and I'll fix it.
• Reusable means canonical, not configurable. The shared asset is one canonical mapping plus a public conformance corpus, not an any-flavor engine. Per-institution variation lives in the client's own code against a typed interface, so the core stays thin instead of collapsing into the complexity you describe.
• Edge representation, not architecture. The on-ledger model stays native. The adapter only lowers the cost of the one boundary institutions are required to speak (Fedwire moved to ISO 20022 in July 2025, and SWIFT MT/ISO coexistence ended in Nov 2025). It shouldn't be where workflows get redesigned, and it shouldn't let them avoid that redesign either.

Where I think you're most right is on demand and on the identity/trust model. Those can't be designed in the abstract. I'm anchoring this around concrete design partners and a specific legacy process, and validating the identity-mapping and trust assumptions directly with the client's team.

Given you've actually been through this, would you be open to reviewing the design with us? Specifically where the "edge" line sits, what must never become configurable, and the identity/trust pitfalls you hit.