January 29, 2020
Authors: Lynn Bendixsen (Sovrin Foundation) and Richard Esplin (Evernym)
With the recent approval of the Sovrin Governance Framework v2, we have a Transaction Author Agreement (TAA) that we can now use on the production Sovrin networks. Last June we posted a blog explaining the TAA with examples, and in this post we will provide further information about how your applications that write to a Sovrin network should support the TAA. Detailed instructions for creating, retrieving, and accepting the TAA are available in the documentation for the Transaction Author Agreement functionality in Hyperledger Indy.
The Transaction Author Agreement informs users about their rights and obligations when using any of the Sovrin networks (MainNet, BuilderNet, StagingNet). It also clarifies the role of Stewards as data processors. As a result, the Sovrin Governance Working Group voted to require Transaction Authors to accept the TAA with every write to the ledger. The text of the agreement was collaboratively developed by the legal teams from multiple Sovrin Stewards and the Sovrin Foundation. The functionality in Hyperledger Indy to support the TAA was designed and developed by the Sovrin Foundation and Evernym. A sample TAA has been enforced on Sovrin BuilderNet since June of 2019, and we are preparing to enforce the official TAA on all public Sovrin networks.
As we have prepared to roll out the TAA, we identified improvements to the behavior of Hyperledger Indy that will make adoption easier. Those improvements are explained in an Evernym Sprint Demo video, and are being rolled out to the Sovrin networks. Once they are rolled out, we can begin enforcing the new TAA on the Sovrin BuilderNet and StagingNet. If you have an application deployed on a Sovrin network, you can smoothly transition as follows:
As the regulatory environment changes, we expect that the TAA will need to evolve. To make this easy, Indy now supports having multiple agreements active on the ledger at a time. Requesting the TAA from the ledger will return the most recent TAA unless a specific version is requested. The most recent version of the agreement will best protect the Sovrin Stewards, as it is the version most recently approved by the Sovrin Governance Framework Working Group.
However, transactions signed with the previous TAA will continue to be accepted by the ledger until the previous TAA is formally retired. This process fulfills the obligation written in the agreement that it cannot be retired until the new agreement has been public for 45 days. After the agreement is formally retired, write transactions that include the hash of the retired agreement will be rejected.
It is expected that application developers will notify their users when a new agreement is available on the ledger, and as soon as their users accept the new agreement they can begin using it to submit transactions. This provides a smooth transition for existing users, while all new Transaction Authors will be using the most recently ratified agreement.
The first time a Transaction Author writes to a Sovrin network, the Author should be shown the TAA and given the opportunity to review and accept it before the write transaction is submitted. In many instances, the software user will be acting on behalf of an organization who is the actual Transaction Author, and the user may not be authorized to accept legal agreements on behalf of the organization. The Acceptance Mechanism List includes mechanisms intended to accommodate these use cases. The TAA acceptance date should reflect when an authorized representative (such as legal counsel) reviewed and accepted the agreement (any time after the agreement was ratified by the Sovrin Governance Framework Working Group). This date might need to be entered by an end user through the user interface or by a system administrator in a configuration file.
The TAA text states that “If Transaction Author continues to Author Transactions to the Sovrin Ledger Networks after the Amendment Cutover Date, such continued use will constitute acceptance of the amended Agreement.” As a result, after the Transaction Author has accepted a version of the agreement the Author does not need to be presented with the full text of an updated agreement. Rather, the TAA acceptance date should reflect when the user was notified that an updated agreement exists on the ledger. The TAA hash should match the version of the agreement that the user was notified is in effect.
Q: How does the ledger verify that the Transaction Author accepts the TAA?
A: Each write transaction must include a hash of the TAA, an acceptance date, and an acceptance mechanism drawn from the list on the ledger which reflects the process that was used for meaningful agreement. The ledger computes a SHA-256 hash from the MarkDown text that is anchored to the ledger for that version of the TAA. This hash is returned in the digest field of GET_TRANSACTION_AUTHOR_AGREEMENT, and can be inserted in a write transaction to signify agreement. Alternatively, the full text can be used to indicate agreement.
For convenience, this hash is also available in the ReadMe for the TAA in GitHub.
Q: What version of the TAA did the Transaction Author review in full?
A: Software used to write to a Sovrin network should display the full text of the agreement the first time a Transaction Author writes to the network. But when the agreement is updated it is only necessary to notify the Author; the full text does not need to be displayed within the application. Interested parties can review the ledger history to determine the first version that was accepted by the Transaction Author, which is the version that should have been displayed to the user in full.
Q: What version of MarkDown is being used?
A: We are using a reduced version of GitHub MarkDown. Specifically, we avoid MarkDown lists where we need to preserve the section numbering, and we do not use embedded HTML that clients might filter as being insecure.
Jira tickets regarding the updated functionality: