From 6f88e8c18c5854147d3dfdde17fba7888eb802dd Mon Sep 17 00:00:00 2001 From: Paul Moloney Date: Wed, 29 Oct 2025 15:07:47 +0000 Subject: [PATCH] DOC-6758 (4.13) Added attachment resolution behaviour update for 4.13 ENT and OS --- .../tutorial-attachments.md | 31 +++++++++++++++++++ .../tutorial-attachments.md | 31 +++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/content/en/platform/corda/4.13/community/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md b/content/en/platform/corda/4.13/community/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md index 387201eaf5..2447646690 100644 --- a/content/en/platform/corda/4.13/community/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md +++ b/content/en/platform/corda/4.13/community/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md @@ -132,6 +132,37 @@ and which are shared explicitly. These are useful for attaching and signing audi that isn’t used as part of the contract logic. {{< /note >}} +## How attachments are resolved + +When building a transaction, Corda automatically tries to resolve any missing class or contract by finding a suitable attachment, using the following order of priority: + +1. **Installed CorDapps first:** Corda searches the locally installed CorDapps directories first for a matching attachment. +2. **Optional database fallback:** If no installed CorDapp is found, and database fallback is enabled, then Corda will search the attachment store (trusted uploaders only). To enable or disable database fallback, use the `net.corda.node.transactionbuilder.missingClassDbSearchDisabled` option; see [Attachment resolution configuration properties]({{< relref "#attachment-resolution-configuration-properties" >}}). +3. **Legacy CorDapps:** Legacy contracts are only resolved using the `legacy-contracts` CorDapps folder; Corda never falls back to the database. +4. **Compatibility filtering:** Attachments with an incompatible Kotlin version are excluded. + +Prior to version 4.12, only the database option was used; this behavior can be restored using the `net.corda.node.transactionbuilder.installedFirstSearchDisabled` option; see [Attachment resolution configuration properties]({{< relref "#attachment-resolution-configuration-properties" >}}). + +### Deterministic attachment selection + +If multiple attachments match, Corda uses deterministic ordering to ensure all nodes pick the same attachment. +Attachments are sorted by: + +1. Version (descending) +2. Insertion date (descending) (for database attachments) +3. ID (ascending) (for installed attachments) + +This prevents runtime-dependent selection and ensures identical transaction builds across the network. + +### Attachment resolution configuration properties + +The following system properties control the lookup logic: + +| Property | Default Value | Description | +|-------------------------------------------------------------------------|---------------|----------------------------------------------------------------------------------------| +| net.corda.node.transactionbuilder.missingClassDbSearchDisabled | false | If true, disables database fallback — only installed CorDapps are searched. | +| net.corda.node.transactionbuilder.installedFirstSearchDisabled | false | If true, restores the database-only lookup behavior used in versions prior to 4.12). | + ## Example Here is a simple example of how to attach a file to a transaction and send it to the counterparty. The full code for this demo can be found in the [Kotlin](https://github.com/corda/samples-kotlin/tree/release/4.13/Features/attachment-sendfile) and [Java](https://github.com/corda/samples-java/tree/release/4.13/Features/attachment-sendfile) sample repositories. diff --git a/content/en/platform/corda/4.13/enterprise/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md b/content/en/platform/corda/4.13/enterprise/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md index 3581e627e1..2786d8bb77 100644 --- a/content/en/platform/corda/4.13/enterprise/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md +++ b/content/en/platform/corda/4.13/enterprise/get-started/tutorials/supplementary-tutorials/tutorial-attachments.md @@ -132,6 +132,37 @@ and which are shared explicitly. These are useful for attaching and signing audi that isn’t used as part of the contract logic. {{< /note >}} +## How attachments are resolved + +When building a transaction, Corda automatically tries to resolve any missing class or contract by finding a suitable attachment, using the following order of priority: + +1. **Installed CorDapps first:** Corda searches the locally installed CorDapps directories first for a matching attachment. +2. **Optional database fallback:** If no installed CorDapp is found, and database fallback is enabled, then Corda will search the attachment store (trusted uploaders only). To enable or disable database fallback, use the `net.corda.node.transactionbuilder.missingClassDbSearchDisabled` option; see [Attachment resolution configuration properties]({{< relref "#attachment-resolution-configuration-properties" >}}). +3. **Legacy CorDapps:** Legacy contracts are only resolved using the `legacy-contracts` CorDapps folder; Corda never falls back to the database. +4. **Compatibility filtering:** Attachments with an incompatible Kotlin version are excluded. + +Prior to version 4.12, only the database option was used; this behavior can be restored using the `net.corda.node.transactionbuilder.installedFirstSearchDisabled` option; see [Attachment resolution configuration properties]({{< relref "#attachment-resolution-configuration-properties" >}}). + +### Deterministic attachment selection + +If multiple attachments match, Corda uses deterministic ordering to ensure all nodes pick the same attachment. +Attachments are sorted by: + +1. Version (descending) +2. Insertion date (descending) (for database attachments) +3. ID (ascending) (for installed attachments) + +This prevents runtime-dependent selection and ensures identical transaction builds across the network. + +### Attachment resolution configuration properties + +The following system properties control the lookup logic: + +| Property | Default Value | Description | +|-------------------------------------------------------------------------|---------------|----------------------------------------------------------------------------------------| +| net.corda.node.transactionbuilder.missingClassDbSearchDisabled | false | If true, disables database fallback — only installed CorDapps are searched. | +| net.corda.node.transactionbuilder.installedFirstSearchDisabled | false | If true, restores the database-only lookup behavior used in versions prior to 4.12). | + ## Example Here is a simple example of how to attach a file to a transaction and send it to the counterparty. The full code for this demo can be found in the [Kotlin](https://github.com/corda/samples-kotlin/tree/release/4.13/Features/attachment-sendfile) and [Java](https://github.com/corda/samples-java/tree/release/4.13/Features/attachment-sendfile) sample repositories.