Archive Service in Corda
The Archive Service allows you to make an archive of transactions and attachments. These transaction from Corda vault can no longer be part of an ongoing or new transaction flow which can reduce pressure on your node’s database, and declutter your vault.
Archive service is available in Corda Enterprise edition and it comes in following flavors.
- Archive Service CorDapp -which contains the necessary flows to mark and archive transactions.
- Archive Service Client Library -which provides programmatic access to the archive service, and exposes relevant APIs.
- Archive Service Command Line Interface -which allows you to perform archiving tasks from the command line.
In this article we will be looking at how the archive service CLI jar is used to archive transactions in Corda.
How archive service CLI works
The Archive Service requires Node minimum platform version 6, Corda Enterprise minimum version 4.4 and LedgerGraph V1.2.The Archive Service CorDapp .jar and the Ledger Service CorDapp .jar file must also be copied to the nodes cordapps directory.
Archive service depends on LedgerGraph in corda. The LedgerGraph is a CorDapp you can use to get in-memory access to transaction data. Transaction information is kept in a graph structure on any node where LedgerGraph is installed. As not all transactions are related to all other transactions, there can actually be multiple components in the graph: each a directed acyclic graph (DAG). Each of these graphs need to be loaded in memory to archive a transaction and transactions with no unconsumed transactions can only be archived.
When using Archive Service CLI jar to execute commands, it should be used from a machine that can issue Corda RPC commands to the node.
To provide the configurations to the Archive Service CLI jar you can use command line argument --node-configuration to specify a file giving the necessary RPC settings to connect to the node (node.conf file) or if the Archive Service is executed from the same directory as the node then the settings are automatically collected from the node’s node.conf file.
Transaction archival using CLI jar is sequence of commands executed from command line.
For Example:
java -jar corda-tools-archive-service-1.0.1.jar list-jobs
Above command will display status of archiving jobs
The archive process consists of a sequence of steps which are executed as commands from the command line.
The archive process starts with the list-items command and completes with the delete-vault command or the delete-snapshot command if the optional backup schema is used.
As part of the configuration process, you can choose to create a backup schema. This is a temporary snapshot image of archivable transactions that can be used to restore the vault if the archiving process fails.
The Archival workflow is as follows:
Filters can be applied to limit which transactions and attachments are available for archiving. The filters to be applied can be given on the command line of the list-items or create-snapshot commands, or recorded in the CorDapp configuration file.
list-items: used to view which transactions and attachments will be archived.create-snapshot: marks the transactions and attachments that will be archived. If a backup schema has been configured then the items are copied from the vault schema to the backup schema.export-snapshot: exports the archivable items to a long-term archive. Corda provides an option to select an exporter for this task.delete-vault: deletes the archived items from the vault.
If you are using a backup schema, then use following command.
delete-snapshot: cleans up the backup schema if a backup schema has been configured.
To revert any steps up to delete-vault or delete-snapshot, use:
restore-snapshot - restores the vault and deletes the snapshot
If you want to get the exported transactions back to the Corda vault for some reasons long after exporting them then you can use following command.
import-snapshot-copy the archived items from a snapshot archive back to the vault.
What can be archived
As we have seen the Archive Service has commands you can use to identify which transactions can be archived in your vault. A fully consumed transaction or attachment will be marked as archivable only when,
- There are no unconsumed transactions in the same LedgerGraph component. (A LedgerGraph component is a connected group of transactions, represented as a Direct Acrylic Graph (DAG) in the LedgerGraph service )
- The transaction is not also referenced by another LedgerGraph component that contains unconsumed transactions.
- The attachment itself is not a contract attachment.
These archivable transactions and attachments are only associated with transactions which have no unconsumed transaction outputs (UTXOs).
References
- https://docs.r3.com/en/platform/corda/4.8/enterprise/node/archiving/archiving-setup.html#archive-service-cordapp
- https://docs.r3.com/en/platform/corda/4.8/enterprise/node/archiving/archiving-cli.html
https://docs.r3.com/en/platform/corda/4.8/enterprise/node/archiving/archiving-cli.html
