2016-09-23 13:41:29 +00:00
|
|
|
.. highlight:: kotlin
|
|
|
|
.. raw:: html
|
|
|
|
|
|
|
|
Using attachments
|
|
|
|
=================
|
|
|
|
|
|
|
|
Attachments are (typically large) Zip/Jar files referenced within a transaction, but not included in the transaction
|
|
|
|
itself. These files can be requested from the originating node as needed, although in many cases will be cached within
|
|
|
|
nodes already. Examples include:
|
|
|
|
|
|
|
|
* Contract executable code
|
|
|
|
* Metadata about a transaction, such as PDF version of an invoice being settled
|
|
|
|
* Shared information to be permanently recorded on the ledger
|
|
|
|
|
|
|
|
To add attachments the file must first be added to the node's storage service using ``StorageService.importAttachment()``,
|
|
|
|
which returns a unique ID that can be added using ``TransactionBuilder.addAttachment()``. Attachments can also be
|
|
|
|
uploaded and downloaded via HTTP, to enable integration with external systems. For instructions on HTTP upload/download
|
|
|
|
please see ":doc:`node-administration`".
|
|
|
|
|
|
|
|
Normally attachments on transactions are fetched automatically via the ``ResolveTransactionsProtocol`` when verifying
|
|
|
|
received transactions. Attachments are needed in order to validate a transaction (they include, for example, the
|
|
|
|
contract code), so must be fetched before the validation process can run. ``ResolveTransactionsProtocol`` calls
|
|
|
|
``FetchTransactionsProtocol`` to perform the actual retrieval.
|
|
|
|
|
|
|
|
It is encouraged that where possible attachments are reusable data, so that nodes can meaningfully cache them.
|
|
|
|
|
|
|
|
Attachments demo
|
|
|
|
----------------
|
|
|
|
|
|
|
|
There is a worked example of attachments, which relays a simple document from one node to another. The "two party
|
|
|
|
trade protocol" also includes an attachment, however it is a significantly more complex demo, and less well suited
|
|
|
|
for a tutorial.
|
|
|
|
|
2016-11-10 13:14:38 +00:00
|
|
|
The demo code is in the file "src/main/kotlin/net.corda.demos/attachment/AttachmentDemo.kt", with the core logic
|
2016-09-23 13:41:29 +00:00
|
|
|
contained within the two functions ``runRecipient()`` and ``runSender()``. We'll look at the recipient function first;
|
|
|
|
this subscribes to notifications of new validated transactions, and if it receives a transaction containing attachments,
|
|
|
|
loads the first attachment from storage, and checks it matches the expected attachment ID. ``ResolveTransactionsProtocol``
|
|
|
|
has already fetched all attachments from the remote node, and as such the attachments are available from the node's
|
|
|
|
storage service. Once the attachment is verified, the node shuts itself down.
|
|
|
|
|
|
|
|
.. sourcecode:: kotlin
|
|
|
|
|
|
|
|
private fun runRecipient(node: Node) {
|
|
|
|
val serviceHub = node.services
|
|
|
|
|
|
|
|
// Normally we would receive the transaction from a more specific protocol, but in this case we let [FinalityProtocol]
|
|
|
|
// handle receiving it for us.
|
|
|
|
serviceHub.storageService.validatedTransactions.updates.subscribe { event ->
|
|
|
|
// When the transaction is received, it's passed through [ResolveTransactionsProtocol], which first fetches any
|
|
|
|
// attachments for us, then verifies the transaction. As such, by the time it hits the validated transaction store,
|
|
|
|
// we have a copy of the attachment.
|
|
|
|
val tx = event.tx
|
|
|
|
if (tx.attachments.isNotEmpty()) {
|
|
|
|
val attachment = serviceHub.storageService.attachments.openAttachment(tx.attachments.first())
|
|
|
|
assertEquals(PROSPECTUS_HASH, attachment?.id)
|
|
|
|
|
|
|
|
println("File received - we're happy!\n\nFinal transaction is:\n\n${Emoji.renderIfSupported(event.tx)}")
|
|
|
|
thread {
|
|
|
|
node.stop()
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
The sender correspondingly builds a transaction with the attachment, then calls ``FinalityProtocol`` to complete the
|
|
|
|
transaction and send it to the recipient node:
|
|
|
|
|
|
|
|
|
|
|
|
.. sourcecode:: kotlin
|
|
|
|
|
|
|
|
private fun runSender(node: Node, otherSide: Party) {
|
|
|
|
val serviceHub = node.services
|
|
|
|
// Make sure we have the file in storage
|
|
|
|
if (serviceHub.storageService.attachments.openAttachment(PROSPECTUS_HASH) == null) {
|
2016-11-10 13:14:38 +00:00
|
|
|
net.corda.demos.Role::class.java.getResourceAsStream("bank-of-london-cp.jar").use {
|
2016-09-23 13:41:29 +00:00
|
|
|
val id = node.storage.attachments.importAttachment(it)
|
|
|
|
assertEquals(PROSPECTUS_HASH, id)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
// Create a trivial transaction that just passes across the attachment - in normal cases there would be
|
|
|
|
// inputs, outputs and commands that refer to this attachment.
|
|
|
|
val ptx = TransactionType.General.Builder(notary = null)
|
|
|
|
ptx.addAttachment(serviceHub.storageService.attachments.openAttachment(PROSPECTUS_HASH)!!.id)
|
|
|
|
|
|
|
|
// Despite not having any states, we have to have at least one signature on the transaction
|
|
|
|
ptx.signWith(ALICE_KEY)
|
|
|
|
|
|
|
|
// Send the transaction to the other recipient
|
|
|
|
val tx = ptx.toSignedTransaction()
|
|
|
|
serviceHub.startProtocol(LOG_SENDER, FinalityProtocol(tx, emptySet(), setOf(otherSide))).success {
|
|
|
|
thread {
|
|
|
|
Thread.sleep(1000L) // Give the other side time to request the attachment
|
|
|
|
node.stop()
|
|
|
|
}
|
|
|
|
}.failure {
|
|
|
|
println("Failed to relay message ")
|
|
|
|
}
|
2016-11-10 13:14:38 +00:00
|
|
|
}
|