From d76448a231270cd2252d05053370bd14b278833d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Wed, 6 Mar 2024 03:11:52 +0000
Subject: [PATCH] Deployed fa2a8ea08 to main with MkDocs 1.5.3 and mike 2.0.0

---
 main/CHANGELOG/index.html                     | 109 ++++++++++--------
 .../demo/AliceWantsAJsonCredential/index.html |   2 +-
 main/demo/AriesOpenAPIDemo/index.html         |   4 +-
 main/features/DIDResolution/index.html        |   2 +-
 main/features/DevReadMe/index.html            |   4 +-
 main/features/Multitenancy/index.html         |   4 +-
 main/features/SupportedRFCs/index.html        |   2 +-
 main/features/devcontainer/index.html         |   2 +-
 main/generated/aries_cloudagent.utils.rst     |   8 ++
 main/search/search_index.json                 |   2 +-
 main/sitemap.xml.gz                           | Bin 127 -> 127 bytes
 11 files changed, 81 insertions(+), 58 deletions(-)

diff --git a/main/CHANGELOG/index.html b/main/CHANGELOG/index.html
index 2bc3f3c82a..89980486be 100644
--- a/main/CHANGELOG/index.html
+++ b/main/CHANGELOG/index.html
@@ -523,28 +523,28 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#0120rc1" class="md-nav__link">
+  <a href="#0120rc2" class="md-nav__link">
     <span class="md-ellipsis">
-      0.12.0rc1
+      0.12.0rc2
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="0.12.0rc1">
+    <nav class="md-nav" aria-label="0.12.0rc2">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#february-17-2024" class="md-nav__link">
+  <a href="#march-5-2024" class="md-nav__link">
     <span class="md-ellipsis">
-      February 17, 2024
+      March 5, 2024
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#0120rc1-breaking-changes" class="md-nav__link">
+  <a href="#0120rc2-breaking-changes" class="md-nav__link">
     <span class="md-ellipsis">
-      0.12.0rc1 Breaking Changes
+      0.12.0rc2 Breaking Changes
     </span>
   </a>
   
@@ -2173,28 +2173,28 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#0120rc1" class="md-nav__link">
+  <a href="#0120rc2" class="md-nav__link">
     <span class="md-ellipsis">
-      0.12.0rc1
+      0.12.0rc2
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="0.12.0rc1">
+    <nav class="md-nav" aria-label="0.12.0rc2">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#february-17-2024" class="md-nav__link">
+  <a href="#march-5-2024" class="md-nav__link">
     <span class="md-ellipsis">
-      February 17, 2024
+      March 5, 2024
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#0120rc1-breaking-changes" class="md-nav__link">
+  <a href="#0120rc2-breaking-changes" class="md-nav__link">
     <span class="md-ellipsis">
-      0.12.0rc1 Breaking Changes
+      0.12.0rc2 Breaking Changes
     </span>
   </a>
   
@@ -2257,24 +2257,26 @@
 
 
 <h1 id="aries-cloud-agent-python-changelog">Aries Cloud Agent Python Changelog<a class="headerlink" href="#aries-cloud-agent-python-changelog" title="Permanent link">&para;</a></h1>
-<h2 id="0120rc1">0.12.0rc1<a class="headerlink" href="#0120rc1" title="Permanent link">&para;</a></h2>
-<h3 id="february-17-2024">February 17, 2024<a class="headerlink" href="#february-17-2024" title="Permanent link">&para;</a></h3>
+<h2 id="0120rc2">0.12.0rc2<a class="headerlink" href="#0120rc2" title="Permanent link">&para;</a></h2>
+<h3 id="march-5-2024">March 5, 2024<a class="headerlink" href="#march-5-2024" title="Permanent link">&para;</a></h3>
 <p>Release 0.12.0 is a relative large release but currently with no breaking changes. We expect there will be breaking changes (at least in the handling of endorsement) before the 0.12.0 release is finalized, hence the minor version update.</p>
-<p>The first <code>rc0</code> release candidate <code>rc0</code> introduced a regression via [PR #2705] that has been reverted in [PR #2789]. Further investigation is needed to determine how to accomplish the goal of [PR #2705] ("feat: inject profile") without the regression.</p>
-<p>Much progress was made on <code>did:peer</code> support in this release, with the handling of inbound <a href="https://identity.foundation/peer-did-method-spec/">DID Peer</a> 1 added, and inbound and outbound support for DID Peer 2 and 4. The goal of that work is to eliminate the remaining places where "unqualified" DIDs remain. Work continues in supporting ledger agnostic <a href="https://www.hyperledger.org/projects/anoncreds">AnonCreds</a>, and the new <a href="https://github.com/hyperledger/anoncreds-rs">Hyperledger AnonCreds Rust</a> library. Attention was also given in the release to the handling of JSON-LD <a href="https://www.w3.org/TR/vc-data-integrity/">Data Integrity Verifiable Credentials</a>, with more expected before the release is finalized. In addition to those updates, there were fixes and improvements across the codebase.</p>
+<p>The <code>rc0</code> release candidate introduced a regression via [PR #2705] that has been reverted in <code>rc1</code> and later via [PR #2789]. Further investigation is needed to determine how to accomplish the goal of [PR #2705] ("feat: inject profile") without the regression. The <code>rc2</code>
+and later releases address a regression related to the sending of a revocation notification from the issuer to the holder of a newly
+revoked credential, fixed in [PR #2814]</p>
+<p>Much progress has been made on <code>did:peer</code> support in this release, with the handling of inbound <a href="https://identity.foundation/peer-did-method-spec/">DID Peer</a> 1 added, and inbound and outbound support for DID Peer 2 and 4. The goal of that work is to eliminate the remaining places where "unqualified" DIDs remain, and to enable the "connection reuse" in the Out of Band protocol when using DID Peer 2 and 4 DIDs. Work continues in supporting ledger agnostic <a href="https://www.hyperledger.org/projects/anoncreds">AnonCreds</a>, and the new <a href="https://github.com/hyperledger/anoncreds-rs">Hyperledger AnonCreds Rust</a> library. Attention was also given in the release to the handling of JSON-LD <a href="https://www.w3.org/TR/vc-data-integrity/">Data Integrity Verifiable Credentials</a>, with more expected before the release is finalized. In addition to those updates, there were fixes and improvements across the codebase.</p>
 <p>The most visible change in this release is the re-organization of the ACA-Py documentation, moving the vast majority of the documents to the folders within the <code>docs</code> folder -- a long overdue change that will allow us to soon publish the documents on <a href="https://aca-py.org">https://aca-py.org</a> directly from the ACA-Py repository, rather than from the separate <a href="https://github.com/hyperledger/aries-acapy-docs">aries-acapy-docs</a> currently being used.</p>
-<p>A big developer improvement is a revampling of the test handling to eliminate ~2500 warnings that were previously generated in the test suite.  Nice job <a href="https://github.com/ff137">@ff137</a>!</p>
-<h3 id="0120rc1-breaking-changes">0.12.0rc1 Breaking Changes<a class="headerlink" href="#0120rc1-breaking-changes" title="Permanent link">&para;</a></h3>
-<p>There are no breaking changes in 0.12.0rc1.</p>
-<!-- Latest: 2756 -->
+<p>A big developer improvement is a revamping of the test handling to eliminate ~2500 warnings that were previously generated in the test suite.  Nice job <a href="https://github.com/ff137">@ff137</a>!</p>
+<h3 id="0120rc2-breaking-changes">0.12.0rc2 Breaking Changes<a class="headerlink" href="#0120rc2-breaking-changes" title="Permanent link">&para;</a></h3>
+<p>There are no breaking changes in 0.12.0rc2.</p>
+<!-- Latest: 2805 -->
 
-<h4 id="0120rc1-categorized-list-of-pull-requests">0.12.0rc1 Categorized List of Pull Requests<a class="headerlink" href="#0120rc1-categorized-list-of-pull-requests" title="Permanent link">&para;</a></h4>
+<h4 id="0120rc2-categorized-list-of-pull-requests">0.12.0rc2 Categorized List of Pull Requests<a class="headerlink" href="#0120rc2-categorized-list-of-pull-requests" title="Permanent link">&para;</a></h4>
 <ul>
 <li>DID Handling and Connection Establishment Updates/Fixes</li>
+<li>Author subwallet setup automation <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2791">#2791</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>fix: save multi_use to the DB for OOB invitations <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2694">#2694</a> <a href="https://github.com/frostyfrog">frostyfrog</a></li>
-<li>Connection and DIDX Problem Reports <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2653">#2653</a> <a href="https://github.com/usingtechnology">usingtechnology</a></li>
 <li>
-<p>Feat: DIDX Implicit Request auto-accept and Delete OOB Invitation related records <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2642">#2642</a> <a href="https://github.com/shaangill025">shaangill025</a></p>
+<p>Connection and DIDX Problem Reports <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2653">#2653</a> <a href="https://github.com/usingtechnology">usingtechnology</a></p>
 </li>
 <li>
 <p>DID Peer and DID Resolver Updates and Fixes</p>
@@ -2291,6 +2293,9 @@ <h4 id="0120rc1-categorized-list-of-pull-requests">0.12.0rc1 Categorized List of
 <li>
 <p>Ledger Agnostic AnonCreds RS Changes</p>
 </li>
+<li>Send revocation list instead of rev_list object - Anoncreds <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2821">#2821</a> <a href="https://github.com/jamshale">jamshale</a></li>
+<li>Fix anoncreds non-endorsement revocation <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2814">#2814</a> <a href="https://github.com/jamshale">jamshale</a>  - Get and create anoncreds profile when using anoncreds subwallet <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2803">#2803</a> <a href="https://github.com/jamshale">jamshale</a></li>
+<li>Add anoncreds multitenant endorsement integration tests <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2801">#2801</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>Anoncreds revoke and publish-revocations endorsement <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2782">#2782</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>Upgrade anoncreds to version 0.2.0-dev11 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2763">#2763</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>Update anoncreds to 0.2.0-dev10 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2758">#2758</a> <a href="https://github.com/jamshale">jamshale</a></li>
@@ -2334,6 +2339,7 @@ <h4 id="0120rc1-categorized-list-of-pull-requests">0.12.0rc1 Categorized List of
 <li>
 <p>Credential Exchange (Issue, Present) Updates</p>
 </li>
+<li>Allow for crids in event payload to be integers <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2819">#2819</a> <a href="https://github.com/jamshale">jamshale</a>  - Create revocation notification after list entry written to ledger <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2812">#2812</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>Remove exception on connectionless presentation problem report handler <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2723">#2723</a> <a href="https://github.com/loneil">loneil</a></li>
 <li>Ensure "preserve_exchange_records" flags are set. <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2664">#2664</a> <a href="https://github.com/usingtechnology">usingtechnology</a></li>
 <li>Slight improvement to credx proof validation error message <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2655">#2655</a> <a href="https://github.com/ianco">ianco</a></li>
@@ -2350,6 +2356,12 @@ <h4 id="0120rc1-categorized-list-of-pull-requests">0.12.0rc1 Categorized List of
 <li>
 <p>Other Fixes, Demo, DevContainer and Documentation Fixes</p>
 </li>
+<li>FIX: GHA update for doc publishing, fix doc file that was blanked <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2820">#2820</a> <a href="https://github.com/swcurran">swcurran</a></li>
+<li>More updates to get docs publishing <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2810">#2810</a> <a href="https://github.com/swcurran">swcurran</a></li>
+<li>Eliminate the double workflow event <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2811">#2811</a> <a href="https://github.com/swcurran">swcurran</a></li>
+<li>Publish docs GHActions tweak <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2806">#2806</a> <a href="https://github.com/swcurran">swcurran</a></li>
+<li>Update publish-docs to operate on main and on branches prefixed with docs-v <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2804">#2804</a> <a href="https://github.com/swcurran">swcurran</a></li>
+<li>Add index.html redirector to gh-pages branch <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2802">#2802</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>Demo description of reuse in establishing a connection <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2787">#2787</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>Reorganize the ACA-Py Documentation Files <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2765">#2765</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>Tweaks to MD files to enable aca-py.org publishing <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2771">#2771</a> <a href="https://github.com/swcurran">swcurran</a></li>
@@ -2366,30 +2378,32 @@ <h4 id="0120rc1-categorized-list-of-pull-requests">0.12.0rc1 Categorized List of
 <li>
 <p>Dependencies and Internal Updates</p>
 </li>
+<li>bot    chore(deps): Bump cryptography from 42.0.3 to 42.0.4  dependencies python <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2805">#2805</a> <a href="https://github.com/dependabot">dependabot</a></li>
+<li>bot    chore(deps): Bump the all-actions group with 3 updates  dependencies github_actions <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2815">#2815</a> <a href="https://github.com/dependabot">dependabot</a></li>
 <li>Change middleware registration order <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2796">#2796</a> <a href="https://github.com/PatStLouis">PatStLouis</a></li>
 <li>Bump pyld version to 2.0.4 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2795">#2795</a> <a href="https://github.com/PatStLouis">PatStLouis</a></li>
 <li>Revert profile inject <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2789">#2789</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>Move emit events to profile and delay sending until after commit <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2760">#2760</a> <a href="https://github.com/ianco">ianco</a></li>
 <li>fix: partial revert of ConnRecord schema change  1.0.0 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2746">#2746</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
-<li>chore(deps): Bump aiohttp from 3.9.1 to 3.9.2  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2745">#2745</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump aiohttp from 3.9.1 to 3.9.2  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2745">#2745</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>bump pydid to v 0.4.3 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2737">#2737</a> <a href="https://github.com/PatStLouis">PatStLouis</a></li>
 <li>Fix subwallet record removal <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2721">#2721</a> <a href="https://github.com/andrewwhitehead">andrewwhitehead</a></li>
-<li>chore(deps): Bump jinja2 from 3.1.2 to 3.1.3  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2707">#2707</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump jinja2 from 3.1.2 to 3.1.3  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2707">#2707</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>feat: inject profile <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2705">#2705</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
 <li>Remove tiny-vim from being added to the container image to reduce reported vulnerabilities from scanning <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2699">#2699</a> <a href="https://github.com/swcurran">swcurran</a></li>
-<li>chore(deps): Bump jwcrypto from 1.5.0 to 1.5.1  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2689">#2689</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump jwcrypto from 1.5.0 to 1.5.1  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2689">#2689</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>Update dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2686">#2686</a> <a href="https://github.com/andrewwhitehead">andrewwhitehead</a></li>
 <li>Fix: Change To Use Timezone Aware UTC datetime <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2679">#2679</a> <a href="https://github.com/Ennovate-com">Ennovate-com</a></li>
 <li>fix: update broken demo dependency <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2638">#2638</a> <a href="https://github.com/mrkaurelius">mrkaurelius</a></li>
-<li>Bump cryptography from 41.0.5 to 41.0.6  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2636">#2636</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>Bump cryptography from 41.0.5 to 41.0.6  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2636">#2636</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>
-<p>Bump aiohttp from 3.8.6 to 3.9.0  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2635">#2635</a> <a href="https://github.com/dependabot bot">dependabot bot</a></p>
+<p>Bump aiohttp from 3.8.6 to 3.9.0  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2635">#2635</a> <a href="https://github.com/dependabot">dependabot bot</a></p>
 </li>
 <li>
 <p>CI/CD, Testing, and Developer Tools/Productivity Updates</p>
 </li>
 <li>Fix deprecation warnings <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2756">#2756</a> <a href="https://github.com/ff137">ff137</a></li>
-<li>chore(deps): Bump the all-actions group with 10 updates  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2784">#2784</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump the all-actions group with 10 updates  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2784">#2784</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>Add Dependabot configuration <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2783">#2783</a> <a href="https://github.com/WadeBarnes">WadeBarnes</a></li>
 <li>Implement B006 rule <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2775">#2775</a> <a href="https://github.com/jamshale">jamshale</a></li>
 <li>⬆️ Upgrade pytest to 8.0 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2773">#2773</a> <a href="https://github.com/ff137">ff137</a></li>
@@ -2404,6 +2418,7 @@ <h4 id="0120rc1-categorized-list-of-pull-requests">0.12.0rc1 Categorized List of
 <li>
 <p>Release management pull requests</p>
 </li>
+<li>0.12.0rc2 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2825">#2825</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>0.12.0rc1 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2800">#2800</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>0.12.0rc1 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2799">#2799</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>0.12.0rc0 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2732">#2732</a> <a href="https://github.com/swcurran">swcurran</a></li>
@@ -2516,11 +2531,11 @@ <h4 id="0110-categorized-list-of-pull-requests">0.11.0 Categorized List of Pull
 <li>Dependencies and Internal Updates</li>
 <li>chore: bump pydid version <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2626">#2626</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
 <li>chore: dependency updates <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2565">#2565</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
-<li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2552">#2552</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
-<li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7 in /demo/playground/scripts  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2551">#2551</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2552">#2552</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
+<li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7 in /demo/playground/scripts  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2551">#2551</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>chore: update pydid <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2527">#2527</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
-<li>chore(deps): Bump urllib3 from 2.0.5 to 2.0.6  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2525">#2525</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
-<li>chore(deps): Bump urllib3 from 2.0.2 to 2.0.6 in /demo/playground/scripts  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2524">#2524</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump urllib3 from 2.0.5 to 2.0.6  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2525">#2525</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
+<li>chore(deps): Bump urllib3 from 2.0.2 to 2.0.6 in /demo/playground/scripts  dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2524">#2524</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>Avoid multiple open wallet connections <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2521">#2521</a> <a href="https://github.com/andrewwhitehead">andrewwhitehead</a></li>
 <li>Remove unused dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2510">#2510</a> <a href="https://github.com/andrewwhitehead">andrewwhitehead</a></li>
 <li>Use correct rust log level in dockerfiles <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2499">#2499</a> <a href="https://github.com/loneil">loneil</a></li>
@@ -2699,7 +2714,7 @@ <h4 id="0100-categorized-list-of-pull-requests">0.10.0 Categorized List of Pull
 <li>Corrected typo on mediator invitation configuration argument <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2365">#2365</a> <a href="https://github.com/jorgefl0">jorgefl0</a></li>
 <li>Add workaround for ARM based macs <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2313">#2313</a> <a href="https://github.com/finnformica">finnformica</a></li>
 <li>Dependencies and Internal Updates</li>
-<li>chore(deps): Bump certifi from 2023.5.7 to 2023.7.22 in /demo/playground/scripts dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2354">#2354</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump certifi from 2023.5.7 to 2023.7.22 in /demo/playground/scripts dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2354">#2354</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>CI/CD and Developer Tools/Productivity Updates</li>
 <li>Fix for nightly tests failing on Python 3.10 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2435">#2435</a> <a href="https://github.com/Gavinok">Gavinok</a></li>
 <li>Don't run Snyk on forks <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2429">#2429</a> <a href="https://github.com/ryjones">ryjones</a></li>
@@ -2795,7 +2810,7 @@ <h4 id="categorized-list-of-pull-requests">Categorized List of Pull Requests<a c
 <li>upgrade requests to latest <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2336">#2336</a> <a href="https://github.com/ff137">ff137</a></li>
 <li>upgrade packaging to latest <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2334">#2334</a> <a href="https://github.com/ff137">ff137</a></li>
 <li>chore: update PyYAML <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2329">#2329</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
-<li>chore(deps): Bump aiohttp from 3.8.4 to 3.8.5 in /demo/playground/scripts dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2325">#2325</a> <a href="https://github.com/dependabot bot">dependabot bot</a></li>
+<li>chore(deps): Bump aiohttp from 3.8.4 to 3.8.5 in /demo/playground/scripts dependencies <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2325">#2325</a> <a href="https://github.com/dependabot">dependabot bot</a></li>
 <li>⬆️ upgrade marshmallow to latest <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2322">#2322</a> <a href="https://github.com/ff137">ff137</a></li>
 <li>fix: use python 3.9 in run_docker <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2291">#2291</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
 <li>BREAKING!: drop python 3.6 support <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2247">#2247</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
@@ -2873,7 +2888,7 @@ <h3 id="april-5-2023">April 5, 2023<a class="headerlink" href="#april-5-2023" ti
 execute the <code>upgrade</code> command. The <code>upgrade</code> command is needed for 0.8.0 Pull
 Request [#2116] - "UPGRADE: Fix multi-use invitation performance", which is
 useful for (at least) deployments of ACA-Py as a mediator. In the release, the
-upgrade process is revamped, and documented in <a href="./UpgradingACA-Py.md">Upgrading ACA-Py</a>.</p>
+upgrade process is revamped, and documented in <a href="../deploying/UpgradingACA-Py/">Upgrading ACA-Py</a>.</p>
 <p>Key points about upgrading for those with production, pre-0.8.1 ACA-Py deployments:</p>
 <ul>
 <li>Upgrades now happen <strong>automatically</strong> on startup, when needed.</li>
@@ -2887,7 +2902,7 @@ <h3 id="april-5-2023">April 5, 2023<a class="headerlink" href="#april-5-2023" ti
 <li>A mechanism is to be added (see <a href="https://github.com/hyperledger/aries-cloudagent-python/issues/2201">Issue #2201</a>) for preventing an upgrade
   running if it should not be run automatically, and requires using the
   <code>upgrade</code> command. To date, there has been no need for this feature.</li>
-<li>See the <a href="./UpgradingACA-Py.md">Upgrading ACA-Py</a> document for more details.</li>
+<li>See the <a href="../deploying/UpgradingACA-Py/">Upgrading ACA-Py</a> document for more details.</li>
 </ul>
 <h4 id="postgres-support-with-aries-askar">Postgres Support with Aries Askar<a class="headerlink" href="#postgres-support-with-aries-askar" title="Permanent link">&para;</a></h4>
 <p>Recent changes to <a href="https://github.com/hyperledger/aries-askar">Aries Askar</a> have resulted in Askar supporting Postgres
@@ -3008,7 +3023,7 @@ <h4 id="upgrade-pr-2116-upgrade-fix-multi-use-invitation-performance">UPGRADE PR
 <h4 id="categorized-list-of-pull-requests_3">Categorized List of Pull Requests<a class="headerlink" href="#categorized-list-of-pull-requests_3" title="Permanent link">&para;</a></h4>
 <ul>
 <li>Verifiable credential, presentation and revocation handling updates</li>
-<li><strong>BREAKING:</strong> Update webhook message to terse form [default, added startup flag --debug-webhooks for full form <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2145">#2145</a> by <a href="victorlee0505">victorlee0505</a></li>
+<li><strong>BREAKING:</strong> Update webhook message to terse form [default, added startup flag --debug-webhooks for full form <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2145">#2145</a> by <a href="https://github.com/victorlee0505">victorlee0505</a></li>
 <li>Add startup flag --light-weight-webhook to trim down outbound webhook payload <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1941">#1941</a> <a href="https://github.com/victorlee0505">victorlee0505</a></li>
 <li>feat: add verification method issue-credentials-2.0/send endpoint <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2135">#2135</a> <a href="https://github.com/chumbert">chumbert</a></li>
 <li>Respect auto-verify-presentation flag in present proof v1 and v2 <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2097">#2097</a> <a href="https://github.com/dbluhm">dbluhm</a></li>
@@ -3095,7 +3110,7 @@ <h4 id="categorized-list-of-pull-requests_3">Categorized List of Pull Requests<a
 <li>
 <p>Startup Command Line / Environment / YAML Parameter Updates</p>
 </li>
-<li>Update webhook message to terse form [default, added startup flag --debug-webhooks for full form <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2145">#2145</a> by <a href="victorlee0505">victorlee0505</a></li>
+<li>Update webhook message to terse form [default, added startup flag --debug-webhooks for full form <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2145">#2145</a> by <a href="https://github.com/victorlee0505">victorlee0505</a></li>
 <li>Add startup flag --light-weight-webhook to trim down outbound webhook payload <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1941">#1941</a> <a href="https://github.com/victorlee0505">victorlee0505</a></li>
 <li>Add missing --mediator-connections-invite cmd arg info to docs <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2051">#2051</a> (<a href="https://github.com/matrixik">matrixik</a>)</li>
 <li>Issue #2068 boolean flag change to support HEAD requests to default route <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2077">#2077</a> (<a href="https://github.com/johnekent">johnekent</a>)</li>
@@ -3131,7 +3146,7 @@ <h4 id="categorized-list-of-pull-requests_3">Categorized List of Pull Requests<a
 </ul>
 </li>
 <li>
-<p>Unit, Integration, and Aries Agent Test Harness Test updates </p>
+<p>Unit, Integration, and Aries Agent Test Harness Test updates</p>
 </li>
 <li>Additional integration tests for revocation scenarios <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2055">#2055</a> (<a href="https://github.com/ianco">ianco</a>)</li>
 <li>
@@ -3173,7 +3188,7 @@ <h4 id="categorized-list-of-pull-requests_3">Categorized List of Pull Requests<a
 <li>[fix] Removes extra comma that prevents swagger from accepting the presentation request <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2149">#2149</a> <a href="https://github.com/swcurran">swcurran</a></li>
 <li>Initial plugin docs <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2138">#2138</a> <a href="https://github.com/ianco">ianco</a></li>
 <li>Acme workshop <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2137">#2137</a> <a href="https://github.com/ianco">ianco</a></li>
-<li>Fix: Performance Demo [no --revocation] <a href="https://github.com/ hyperledger/aries-cloudagent-python/pull/2151">#2151</a> <a href="https://github.com/shaangill025">shaangill025</a></li>
+<li>Fix: Performance Demo [no --revocation] <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2151">#2151</a> <a href="https://github.com/shaangill025">shaangill025</a></li>
 <li>Fix typos in alice-local.sh &amp; faber-local.sh <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2010">#2010</a> (<a href="https://github.com/naonishijima">naonishijima</a>)</li>
 <li>Added a bit about manually creating a revoc reg tails file <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2012">#2012</a> (<a href="https://github.com/ianco">ianco</a>)</li>
 <li>Add ability to set docker container name <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/2024">#2024</a> (<a href="https://github.com/matrixik">matrixik</a>)</li>
@@ -3494,7 +3509,7 @@ <h3 id="january-10-2022">January 10, 2022<a class="headerlink" href="#january-10
 <p>The following is an annotated list of PRs in the release, including a link to each PR.</p>
 <ul>
 <li><strong>AIP 2.0 Features</strong></li>
-<li>Discover Features Protocol: v1_0 refactoring and v2_0 implementation <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1500"><a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1500">#1500</a></a><ul>
+<li>Discover Features Protocol: v1_0 refactoring and v2_0 implementation <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1500">#1500</a><ul>
 <li>Updates the Discover Features 1.0 (AIP 1.0) implementation and implements the new 2.0 version. In doing so, adds generalized support for goal codes to ACA-Py.</li>
 <li>fix DiscoveryExchangeRecord RECORD_TOPIC typo fix <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1566">#1566</a></li>
 </ul>
@@ -3583,7 +3598,7 @@ <h3 id="november-15-2021">November 15, 2021<a class="headerlink" href="#november
 With usage in the field increasing, we're cleaning up edge cases and issues related to volume deployments.</p>
 <p>The most significant new feature for users of Indy ledgers is a simplified approach for transaction authors getting their transactions
 signed by an endorser. Transaction author controllers now do almost nothing other than configuring their instance to use an Endorser,
-and ACA-Py takes care of the rest. Documentation of that feature is <a href="Endorser.md">here</a>.</p>
+and ACA-Py takes care of the rest. Documentation of that feature is <a href="../features/Endorser/">here</a>.</p>
 <ul>
 <li>Improve cloud native deployments/scaling</li>
 <li>unprotect liveness and readiness endpoints <a href="https://github.com/hyperledger/aries-cloudagent-python/pull/1416">#1416</a></li>
@@ -3687,9 +3702,9 @@ <h2 id="060">0.6.0<a class="headerlink" href="#060" title="Permanent link">&para
 <h3 id="february-25-2021">February 25, 2021<a class="headerlink" href="#february-25-2021" title="Permanent link">&para;</a></h3>
 <p>This is a significant release of ACA-Py with several new features, as well as changes to the internal architecture in order to set the groundwork for using the new shared component libraries: <a href="https://github.com/hyperledger/indy-vdr">indy-vdr</a>, <a href="https://github.com/hyperledger/indy-shared-rs">indy-credx</a>, and <a href="https://github.com/hyperledger/aries-askar">aries-askar</a>.</p>
 <h4 id="mediator-support">Mediator support<a class="headerlink" href="#mediator-support" title="Permanent link">&para;</a></h4>
-<p>While ACA-Py had previous support for a basic routing protocol, this was never fully developed or used in practice. Starting with this release, inbound and outbound connections can be established through a mediator agent using the Aries (Mediator Coordination Protocol)[<a href="https://github.com/hyperledger/aries-rfcs/tree/master/features/0211-route-coordination">https://github.com/hyperledger/aries-rfcs/tree/master/features/0211-route-coordination</a>]. This work was initially contributed by Adam Burdett and Daniel Bluhm of <a href="https://indicio.tech/">Indicio</a> on behalf of <a href="https://sicpa.com/">SICPA</a>. <a href="./Mediation.md">Read more about mediation support</a>.</p>
+<p>While ACA-Py had previous support for a basic routing protocol, this was never fully developed or used in practice. Starting with this release, inbound and outbound connections can be established through a mediator agent using the Aries <a href="https://github.com/hyperledger/aries-rfcs/tree/master/features/0211-route-coordination">Mediator Coordination Protocol</a>. This work was initially contributed by Adam Burdett and Daniel Bluhm of <a href="https://indicio.tech/">Indicio</a> on behalf of <a href="https://sicpa.com/">SICPA</a>. <a href="../features/Mediation/">Read more about mediation support</a>.</p>
 <h4 id="multi-tenancy-support">Multi-Tenancy support<a class="headerlink" href="#multi-tenancy-support" title="Permanent link">&para;</a></h4>
-<p>Started by <a href="https://bmw.com/">BMW</a> and completed by <a href="https://animo.id/">Animo Solutions</a> and <a href="https://anon-solutions.ca/">Anon Solutions</a> on behalf of <a href="https://sicpa.com/">SICPA</a>, this feature allows for a single ACA-Py instance to host multiple wallet instances. This can greatly reduce the resources required when many identities are being handled. <a href="./Multitenancy.md">Read more about multi-tenancy support</a>.</p>
+<p>Started by <a href="https://bmw.com/">BMW</a> and completed by <a href="https://animo.id/">Animo Solutions</a> and <a href="https://anon-solutions.ca/">Anon Solutions</a> on behalf of <a href="https://sicpa.com/">SICPA</a>, this feature allows for a single ACA-Py instance to host multiple wallet instances. This can greatly reduce the resources required when many identities are being handled. <a href="../features/Multitenancy/">Read more about multi-tenancy support</a>.</p>
 <h4 id="new-connection-protocols">New connection protocol(s)<a class="headerlink" href="#new-connection-protocols" title="Permanent link">&para;</a></h4>
 <p>In addition to the Aries 0160 Connections RFC, ACA-Py now supports the Aries <a href="https://github.com/hyperledger/aries-rfcs/tree/master/features/0023-did-exchange">DID Exchange Protocol</a> for connection establishment and reuse, as well as the Aries <a href="https://github.com/hyperledger/aries-rfcs/tree/master/features/0434-outofband">Out-of-Band Protocol</a> for representing connection invitations and other pre-connection requests.</p>
 <h4 id="issue-credential-v2">Issue-Credential v2<a class="headerlink" href="#issue-credential-v2" title="Permanent link">&para;</a></h4>
diff --git a/main/demo/AliceWantsAJsonCredential/index.html b/main/demo/AliceWantsAJsonCredential/index.html
index e065ef1017..adc2dbb36d 100644
--- a/main/demo/AliceWantsAJsonCredential/index.html
+++ b/main/demo/AliceWantsAJsonCredential/index.html
@@ -2276,7 +2276,7 @@
 
 <h1 id="how-to-issue-json-ld-credentials-using-aca-py">How to Issue JSON-LD Credentials using ACA-Py<a class="headerlink" href="#how-to-issue-json-ld-credentials-using-aca-py" title="Permanent link">&para;</a></h1>
 <p>ACA-Py has the capability to issue and verify both Indy and JSON-LD (W3C compliant) credentials.</p>
-<p>The JSON-LD support is documented <a href="../JsonLdCredentials.md">here</a> - this document will provide some additional detail in how to use the demo and admin api to issue and prove JSON-LD credentials.</p>
+<p>The JSON-LD support is documented <a href="../../features/JsonLdCredentials/">here</a> - this document will provide some additional detail in how to use the demo and admin api to issue and prove JSON-LD credentials.</p>
 <h2 id="setup-agents-to-issue-json-ld-credentials">Setup Agents to Issue JSON-LD Credentials<a class="headerlink" href="#setup-agents-to-issue-json-ld-credentials" title="Permanent link">&para;</a></h2>
 <p>Clone this repository to a directory on your local:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/hyperledger/aries-cloudagent-python.git
diff --git a/main/demo/AriesOpenAPIDemo/index.html b/main/demo/AriesOpenAPIDemo/index.html
index 08f7dd2d90..3150da24f3 100644
--- a/main/demo/AriesOpenAPIDemo/index.html
+++ b/main/demo/AriesOpenAPIDemo/index.html
@@ -2538,7 +2538,7 @@ <h3 id="issue-credential-notes">Issue Credential Notes<a class="headerlink" href
 </ul>
 <h3 id="bonus-points">Bonus Points<a class="headerlink" href="#bonus-points" title="Permanent link">&para;</a></h3>
 <p>If you would like to perform all of the issuance steps manually on the Faber agent side, use a sequence of the other <code>/issue-credential-2.0/</code> messages. Use the <strong><code>GET /issue-credential-2.0/records</code></strong> to both check the credential exchange state as you progress through the protocol and to find some of the data you’ll need in executing the sequence of requests.</p>
-<p>The following table lists endpoints that you need to call ("REST service") and callbacks that your agent will receive ("callback") that your need to respond to. See the <a href="../features/AdminAPI">detailed API docs</a>.</p>
+<p>The following table lists endpoints that you need to call ("REST service") and callbacks that your agent will receive ("callback") that your need to respond to. See the <a href="../../features/AdminAPI/">detailed API docs</a>.</p>
 <table>
 <thead>
 <tr>
@@ -2692,7 +2692,7 @@ <h3 id="present-proof-notes">Present Proof Notes<a class="headerlink" href="#pre
 <p>As with the issue credential process, the agents handled some of the presentation steps without bothering the controller. In this case, Alice's agent processed the presentation request automatically through its handler for the <code>present_proof_v2_0</code> event, and her wallet contained exactly one credential that satisfied the presentation-request from the Faber agent. Similarly, the Faber agent's handler for the event responds automatically and so on receipt of the presentation, it verified the presentation and updated the status accordingly.</p>
 <h3 id="bonus-points_1">Bonus Points<a class="headerlink" href="#bonus-points_1" title="Permanent link">&para;</a></h3>
 <p>If you would like to perform all of the proof request/response steps manually, you can call all of the individual <code>/present-proof-2.0</code> messages.</p>
-<p>The following table lists endpoints that you need to call ("REST service") and callbacks that your agent will receive ("callback") that you need to respond to. See the <a href="../features/AdminAPI">detailed API docs</a>.</p>
+<p>The following table lists endpoints that you need to call ("REST service") and callbacks that your agent will receive ("callback") that you need to respond to. See the <a href="../../features/AdminAPI/">detailed API docs</a>.</p>
 <table>
 <thead>
 <tr>
diff --git a/main/features/DIDResolution/index.html b/main/features/DIDResolution/index.html
index 14d3de1d10..c6448a5c0f 100644
--- a/main/features/DIDResolution/index.html
+++ b/main/features/DIDResolution/index.html
@@ -2430,7 +2430,7 @@ <h3 id="using-resolver-plugins">Using Resolver Plugins<a class="headerlink" href
 </code></pre></div>
 <p>The following is a fully functional Dockerfile encapsulating this setup:</p>
 <p>```dockerfile=
-FROM ghcr.io/hyperledger/aries-cloudagent-python:py3.9-0.12.0rc1
+FROM ghcr.io/hyperledger/aries-cloudagent-python:py3.9-0.12.0rc2
 RUN pip3 install git+<a href="https://github.com/dbluhm/acapy-resolver-github">https://github.com/dbluhm/acapy-resolver-github</a></p>
 <p>CMD ["aca-py", "start", "-it", "http", "0.0.0.0", "3000", "-ot", "http", "-e", "<a href="http://localhost:3000">http://localhost:3000</a>", "--admin", "0.0.0.0", "3001", "--admin-insecure-mode", "--no-ledger", "--plugin", "acapy_resolver_github"]
 <div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>To use the above dockerfile:
diff --git a/main/features/DevReadMe/index.html b/main/features/DevReadMe/index.html
index f9046a79f1..62649d5746 100644
--- a/main/features/DevReadMe/index.html
+++ b/main/features/DevReadMe/index.html
@@ -2545,7 +2545,7 @@
 
 
 <h1 id="developers-read-me-for-hyperledger-aries-cloud-agent-python">Developer's Read Me for Hyperledger Aries Cloud Agent - Python <!-- omit in toc --><a class="headerlink" href="#developers-read-me-for-hyperledger-aries-cloud-agent-python" title="Permanent link">&para;</a></h1>
-<p>See the <a href="../../README.md">README</a> for details about this repository and information about how the Aries Cloud Agent - Python fits into the Aries project and relates to Indy.</p>
+<p>See the <a href="../../">README</a> for details about this repository and information about how the Aries Cloud Agent - Python fits into the Aries project and relates to Indy.</p>
 <h2 id="table-of-contents">Table of Contents <!-- omit in toc --><a class="headerlink" href="#table-of-contents" title="Permanent link">&para;</a></h2>
 <ul>
 <li><a href="#introduction">Introduction</a></li>
@@ -2684,7 +2684,7 @@ <h2 id="development-workflow">Development Workflow<a class="headerlink" href="#d
 <p>Tests should reside in a directory named <code>tests</code> alongside the code under test. Generally, there is one test file for each file module under test. Test files <em>must</em> have a name starting with <code>test_</code> to be automatically picked up the test runner.</p>
 <p>There are some good examples of various test scenarios for you to work from including mocking external imports and working with async code so take a look around!</p>
 <p>The test suite also displays the current code coverage after each run so you can see how much of your work is covered by tests. Use your best judgement for how much coverage is sufficient.</p>
-<p>Please also refer to the <a href="../../CONTRIBUTING.md">contributing guidelines</a> and <a href="../../CODE_OF_CONDUCT.md">code of conduct</a>.</p>
+<p>Please also refer to the <a href="../../CONTRIBUTING/">contributing guidelines</a> and <a href="../../CODE_OF_CONDUCT.md">code of conduct</a>.</p>
 <h2 id="publishing-releases">Publishing Releases<a class="headerlink" href="#publishing-releases" title="Permanent link">&para;</a></h2>
 <p>The <a href="https://github.com/hyperledger/aries-cloudagent-python/blob/main/PUBLISHING.md">publishing</a> document provides information on tagging a release and publishing the release artifacts to PyPi.</p>
 <h2 id="dynamic-injection-of-services">Dynamic Injection of Services<a class="headerlink" href="#dynamic-injection-of-services" title="Permanent link">&para;</a></h2>
diff --git a/main/features/Multitenancy/index.html b/main/features/Multitenancy/index.html
index 3969a04635..ddc5a35799 100644
--- a/main/features/Multitenancy/index.html
+++ b/main/features/Multitenancy/index.html
@@ -2648,7 +2648,7 @@ <h3 id="base-and-sub-wallets">Base and Sub Wallets<a class="headerlink" href="#b
 <p>Multi-tenancy in ACA-Py makes a distinction between a base wallet and sub wallets.</p>
 <p>The wallets used by the different tenants are called <strong>sub wallets</strong>. A sub wallet is almost identical to a wallet when multi-tenancy is disabled. This means that you can do everything with it that a single-tenant ACA-Py instance can also do.</p>
 <p>The <strong>base wallet</strong> however, takes on a different role and has limited functionality. Its main function is to manage the sub wallets, which can be done using the <a href="#multi-tenant-admin-api">Multi-tenant Admin API</a>. It stores all settings and information about the different sub wallets and will route incoming messages to the corresponding sub wallets. See <a href="#message-routing">Message Routing</a> for more details. All other features are disabled for the base wallet. This means it cannot issue credentials, present proof, or do any of the other actions sub wallets can do. This is to keep a clear hierarchical difference between base and sub wallets. For this reason, the base wallet should generally <em>not</em> be provisioned using the <code>--wallet-seed</code> argument as not only it is not necessary for sub wallet management operations, but it will also require this DID to be correctly registered on the ledger for the service to start-up correctly.</p>
-<p><img alt="Multi-tenancy Architecture" src="/docs/assets/multitenancyDiagram.png" /></p>
+<p><img alt="Multi-tenancy Architecture" src="../../assets/multitenancyDiagram.png" /></p>
 <h3 id="usage">Usage<a class="headerlink" href="#usage" title="Permanent link">&para;</a></h3>
 <p>Multi-tenancy is disabled by default. You can enable support for multiple wallets using the <code>--multitenant</code> startup parameter. To also be able to manage wallets for the tenants, the multi-tenant admin API can be enabled using the <code>--multitenant-admin</code> startup parameter. See <a href="#multi-tenant-admin-api">Multi-tenant Admin API</a> below for more info on the admin API.</p>
 <p>The <code>--jwt-secret</code> startup parameter is required when multi-tenancy is enabled. This is used for JWT creation and verification. See <a href="#authentication">Authentication</a> below for more info.</p>
@@ -2826,7 +2826,7 @@ <h3 id="jwt-secret">JWT Secret<a class="headerlink" href="#jwt-secret" title="Pe
 <p>For deterministic JWT creation and verification between restarts and multiple instances, the same JWT secret would need to be used. Therefore a <code>--jwt-secret</code> param is added to the ACA-Py agent that will be used for JWT creation and verification.</p>
 <h3 id="swaggerui">SwaggerUI<a class="headerlink" href="#swaggerui" title="Permanent link">&para;</a></h3>
 <p>When using the SwaggerUI you can click the <img alt="🔒" class="twemoji" src="https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.0.3/assets/svg/1f512.svg" title=":lock:" /> icon next to each of the endpoints or the <code>Authorize</code> button at the top to set the correct authentication headers. Make sure to also include the <code>Bearer</code> part in the input field. This won't be automatically added.</p>
-<p><img alt="API Authentication" src="/docs/assets/adminApiAuthentication.png" /></p>
+<p><img alt="API Authentication" src="../../assets/adminApiAuthentication.png" /></p>
 <h2 id="tenant-management">Tenant Management<a class="headerlink" href="#tenant-management" title="Permanent link">&para;</a></h2>
 <p>After registering a tenant which effectively creates a subwallet, you may need to update the tenant information or delete it.  The following describes how to accomplish both goals.</p>
 <h3 id="update-a-tenant">Update a tenant<a class="headerlink" href="#update-a-tenant" title="Permanent link">&para;</a></h3>
diff --git a/main/features/SupportedRFCs/index.html b/main/features/SupportedRFCs/index.html
index a3eb1d2452..eb9959d7f1 100644
--- a/main/features/SupportedRFCs/index.html
+++ b/main/features/SupportedRFCs/index.html
@@ -2342,7 +2342,7 @@ <h1 id="aries-aip-and-rfcs-supported-in-aries-cloud-agent-python">Aries AIP and
 ACA-Py or the repository <code>main</code> branch. Reminders (and PRs!) to update this page are
 welcome! If you have any questions, please contact us on the #aries channel on
 <a href="https://discord.gg/hyperledger">Hyperledger Discord</a> or through an issue in this repo.</p>
-<p><strong>Last Update</strong>: 2024-02-17, Release 0.12.0rc1</p>
+<p><strong>Last Update</strong>: 2024-03-05, Release 0.12.0rc2</p>
 <blockquote>
 <p>The checklist version of this document was created as a joint effort
 between <a href="https://northernblock.io/">Northern Block</a>, <a href="https://animo.id/">Animo Solutions</a> and the Ontario government, on behalf of the Ontario government.</p>
diff --git a/main/features/devcontainer/index.html b/main/features/devcontainer/index.html
index 5a8a103bbe..1a08b19515 100644
--- a/main/features/devcontainer/index.html
+++ b/main/features/devcontainer/index.html
@@ -2452,7 +2452,7 @@ <h1 id="aca-py-development-with-dev-container">ACA-Py Development with Dev Conta
 <p>The following guide will get you up and running and developing/debugging ACA-Py as quickly as possible.
 We provide a <a href="https://containers.dev"><code>devcontainer</code></a> and will use <a href="https://code.visualstudio.com"><code>VS Code</code></a> to illustrate.</p>
 <p>By no means is ACA-Py limited to these tools; they are merely examples.  </p>
-<p><strong>For information on running demos and tests using provided shell scripts, see <a href="./DevReadMe">DevReadMe</a> readme.</strong></p>
+<p><strong>For information on running demos and tests using provided shell scripts, see <a href="../DevReadMe/">DevReadMe</a> readme.</strong></p>
 <h2 id="caveats">Caveats<a class="headerlink" href="#caveats" title="Permanent link">&para;</a></h2>
 <p>The primary use case for this <code>devcontainer</code> is for developing, debugging and unit testing (pytest) the <a href="https://github.com/hyperledger/aries-cloudagent-python/tree/main/aries_cloudagent">aries_cloudagent</a> source code.</p>
 <p>There are limitations running this devcontainer, such as all networking is within this container. This container has <a href="https://github.com/microsoft/vscode-dev-containers/blob/main/script-library/docs/docker-in-docker.md">docker-in-docker</a> which allows running demos, building docker images, running <code>docker compose</code> all within this container.</p>
diff --git a/main/generated/aries_cloudagent.utils.rst b/main/generated/aries_cloudagent.utils.rst
index b551a25674..b231555d64 100644
--- a/main/generated/aries_cloudagent.utils.rst
+++ b/main/generated/aries_cloudagent.utils.rst
@@ -33,6 +33,14 @@ aries\_cloudagent.utils.dependencies module
    :undoc-members:
    :show-inheritance:
 
+aries\_cloudagent.utils.endorsement\_setup module
+-------------------------------------------------
+
+.. automodule:: aries_cloudagent.utils.endorsement_setup
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 aries\_cloudagent.utils.env module
 ----------------------------------
 
diff --git a/main/search/search_index.json b/main/search/search_index.json
index cf44053fca..b22bef5b79 100644
--- a/main/search/search_index.json
+++ b/main/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Hyperledger Aries Cloud Agent - Python","text":"<p>An easy to use Aries agent for building SSI services using any language that supports sending/receiving HTTP requests.</p> <p>Full access to an organized set of all of the ACA-Py documents is available at https://aca-py.org. Check it out! It's much easier to navigate than this GitHub repo for reading the documentation.</p>"},{"location":"#overview","title":"Overview","text":"<p>Hyperledger Aries Cloud Agent Python (ACA-Py) is a foundation for building Verifiable Credential (VC) ecosystems. It operates in the second and third layers of the Trust Over IP framework (PDF) using DIDComm messaging and Hyperledger Aries protocols. The \"cloud\" in the name means that ACA-Py runs on servers (cloud, enterprise, IoT devices, and so forth), and is not designed to run on mobile devices.</p> <p>ACA-Py is built on the Aries concepts and features that make up Aries Interop Profile (AIP) 2.0. ACA-Py\u2019s supported Aries protocols include, most importantly, protocols for issuing, verifying, and holding verifiable credentials using both Hyperledger AnonCreds verifiable credential format, and the W3C Standard Verifiable Credential Data Model format using JSON-LD with LD-Signatures and BBS+ Signatures. Coming soon -- issuing and presenting Hyperledger AnonCreds verifiable credentials using the W3C Standard Verifiable Credential Data Model format.</p> <p>To use ACA-Py you create a business logic controller that \"talks to\" an ACA-Py instance (sending HTTP requests and receiving webhook notifications), and ACA-Py handles the Aries and DIDComm protocols and related functionality. Your controller can be built in any language that supports making and receiving HTTP requests; knowledge of Python is not needed. Together, this means you can focus on building VC solutions using familiar web development technologies, instead of having to learn the nuts and bolts of low-level cryptography and Trust over IP-type Aries protocols.</p> <p>This checklist-style overview document provides a full list of the features in ACA-Py. The following is a list of some of the core features needed for a production deployment, with a link to detailed information about the capability.</p>"},{"location":"#multi-tenant","title":"Multi-Tenant","text":"<p>ACA-Py supports \"multi-tenant\" scenarios. In these scenarios, one (scalable) instance of ACA-Py uses one database instance, and are together capable of managing separate secure storage (for private keys, DIDs, credentials, etc.) for many different actors. This enables (for example) an \"issuer-as-a-service\", where an enterprise may have many VC issuers, each with different identifiers, using the same instance of ACA-Py to interact with VC holders as required. Likewise, an ACA-Py instance could be a \"cloud wallet\" for many holders (e.g. people or organizations) that, for whatever reason, cannot use a mobile device for a wallet. Learn more about multi-tenant deployments here.</p>"},{"location":"#mediator-service","title":"Mediator Service","text":"<p>Startup options allow the use of an ACA-Py as an Aries mediator using core Aries protocols to coordinate its mediation role. Such an ACA-Py instance receives, stores and forwards messages to Aries  agents that (for example) lack an addressable endpoint on the Internet such as a mobile wallet. A live instance of a public mediator based on ACA-Py is available here from Indicio Technologies. Learn more about deploying a mediator here. See the Aries Mediator Service for a \"best practices\" configuration of an Aries mediator.</p>"},{"location":"#indy-transaction-endorsing","title":"Indy Transaction Endorsing","text":"<p>ACA-Py supports a Transaction Endorsement protocol, for agents that don't have write access to an Indy ledger.  Endorser support is documented here.</p>"},{"location":"#scaled-deployments","title":"Scaled Deployments","text":"<p>ACA-Py supports deployments in scaled environments such as in Kubernetes environments where ACA-Py and its storage components can be horizontally scaled as needed to handle the load.</p>"},{"location":"#vc-api-endpoints","title":"VC-API Endpoints","text":"<p>A set of endpoints conforming to the vc-api specification are included to manage w3c credentials and presentations. They are documented here and a postman demo is available here.</p>"},{"location":"#example-uses","title":"Example Uses","text":"<p>The business logic you use with ACA-Py is limited only by your imagination. Possible applications include:</p> <ul> <li>An interface to a legacy system to issue verifiable credentials</li> <li>An authentication service based on the presentation of verifiable credential proofs</li> <li>An enterprise wallet to hold and present verifiable credentials about that enterprise</li> <li>A user interface for a person to use a wallet not stored on a mobile device</li> <li>An application embedded in an IoT device, capable of issuing verifiable credentials about collected data</li> <li>A persistent connection to other agents that enables secure messaging and notifications</li> <li>Custom code to implement a new service.</li> </ul>"},{"location":"#getting-started","title":"Getting Started","text":"<p>For those new to SSI, Aries and ACA-Py, there are a couple of Linux Foundation edX courses that provide a good starting point.</p> <ul> <li>Identity in Hyperledger: Indy, Aries and Ursa</li> <li>Becoming a Hyperledger Aries Developer</li> </ul> <p>The latter is the most useful for developers wanting to get a solid basis in using ACA-Py and other Aries Frameworks.</p> <p>Also included here is a much more concise (but less maintained) Getting Started Guide that will take you from knowing next to nothing about decentralized identity to developing Aries-based business apps and services. You\u2019ll run an Indy ledger (with no ramp-up time), ACA-Py apps and developer-oriented demos. The guide has a table of contents so you can skip the parts you already know.</p>"},{"location":"#understanding-the-architecture","title":"Understanding the Architecture","text":"<p>There is an architectural deep dive webinar presented by the ACA-Py team, and slides from the webinar are also available. The picture below gives a quick overview of the architecture, showing an instance of ACA-Py, a controller and the interfaces between the controller and ACA-Py, and the external paths to other agents and public ledgers on the Internet.</p> <p></p> <p>You can extend ACA-Py using plug-ins, which can be loaded at runtime.  Plug-ins are mentioned in the webinar and are described in more detail here. An ever-expanding set of ACA-Py plugins can be found in the Aries ACA-Py Plugins repository. Check them out -- it might have the very plugin you need!</p>"},{"location":"#installation-and-usage","title":"Installation and Usage","text":"<p>Use the \"install and go\" page for developers if you are comfortable with Trust over IP and Aries concepts. ACA-Py can be run with Docker without installation (highly recommended), or can be installed from PyPi. In the /demo directory there is a full set of demos for developers to use in getting started, and the demo read me is a great starting point for developers to use an \"in-browser\" approach to run a zero-install example. The Read the Docs overview is also a way to understand the internal modules and APIs that make up an ACA-Py instance.</p> <p>If you would like to develop on ACA-Py locally note that we use Poetry for dependency management and packaging, if you are unfamiliar with poetry please see our cheat sheet</p>"},{"location":"#about-the-aca-py-admin-api","title":"About the ACA-Py Admin API","text":"<p>The overview of ACA-Py\u2019s API is a great starting place for learning about the ACA-Py API when you are starting to build your own controller.</p> <p>An ACA-Py instance puts together an OpenAPI-documented REST interface based on the protocols that are loaded. This is used by a controller application (written in any language) to manage the behavior of the agent. The controller can initiate actions (e.g. issuing a credential) and can respond to agent events (e.g. sending a presentation request after a connection is accepted). Agent events are delivered to the controller as webhooks to a configured URL.</p> <p>Technical note: the administrative API exposed by the agent for the controller to use must be protected with an API key (using the --admin-api-key command line arg) or deliberately left unsecured using the --admin-insecure-mode command line arg. The latter should not be used other than in development if the API is not otherwise secured.</p>"},{"location":"#troubleshooting","title":"Troubleshooting","text":"<p>There are a number of resources for getting help with ACA-Py and troubleshooting any problems you might run into. The Troubleshooting document contains some guidance about issues that have been experienced in the past. Feel free to submit PRs to supplement the troubleshooting document! Searching the ACA-Py GitHub issues may uncovers challenges you are having that others have experienced, often with solutions. As well, there is the \"aries-cloudagent-python\" channel on the Hyperledger Discord chat server (invitation here).</p>"},{"location":"#credit","title":"Credit","text":"<p>The initial implementation of ACA-Py was developed by the Government of British Columbia\u2019s Digital Trust Team in Canada. To learn more about what\u2019s happening with decentralized identity and digital trust in British Columbia, checkout the BC Digital Trust website.</p> <p>See the MAINTAINERS.md file for a list of the current ACA-Py maintainers, and the guidelines for becoming a Maintainer. We'd love to have you join the team if you are willing and able to carry out the duties of a Maintainer.</p>"},{"location":"#contributing","title":"Contributing","text":"<p>Pull requests are welcome! Please read our contributions guide and submit your PRs. We enforce developer certificate of origin (DCO) commit signing \u2014\u00a0guidance on this is available. We also welcome issues submitted about problems you encounter in using ACA-Py.</p>"},{"location":"#license","title":"License","text":"<p>Apache License Version 2.0</p>"},{"location":"CHANGELOG/","title":"Aries Cloud Agent Python Changelog","text":""},{"location":"CHANGELOG/#0120rc1","title":"0.12.0rc1","text":""},{"location":"CHANGELOG/#february-17-2024","title":"February 17, 2024","text":"<p>Release 0.12.0 is a relative large release but currently with no breaking changes. We expect there will be breaking changes (at least in the handling of endorsement) before the 0.12.0 release is finalized, hence the minor version update.</p> <p>The first <code>rc0</code> release candidate <code>rc0</code> introduced a regression via [PR #2705] that has been reverted in [PR #2789]. Further investigation is needed to determine how to accomplish the goal of [PR #2705] (\"feat: inject profile\") without the regression.</p> <p>Much progress was made on <code>did:peer</code> support in this release, with the handling of inbound DID Peer 1 added, and inbound and outbound support for DID Peer 2 and 4. The goal of that work is to eliminate the remaining places where \"unqualified\" DIDs remain. Work continues in supporting ledger agnostic AnonCreds, and the new Hyperledger AnonCreds Rust library. Attention was also given in the release to the handling of JSON-LD Data Integrity Verifiable Credentials, with more expected before the release is finalized. In addition to those updates, there were fixes and improvements across the codebase.</p> <p>The most visible change in this release is the re-organization of the ACA-Py documentation, moving the vast majority of the documents to the folders within the <code>docs</code> folder -- a long overdue change that will allow us to soon publish the documents on https://aca-py.org directly from the ACA-Py repository, rather than from the separate aries-acapy-docs currently being used.</p> <p>A big developer improvement is a revampling of the test handling to eliminate ~2500 warnings that were previously generated in the test suite.  Nice job @ff137!</p>"},{"location":"CHANGELOG/#0120rc1-breaking-changes","title":"0.12.0rc1 Breaking Changes","text":"<p>There are no breaking changes in 0.12.0rc1.</p>"},{"location":"CHANGELOG/#0120rc1-categorized-list-of-pull-requests","title":"0.12.0rc1 Categorized List of Pull Requests","text":"<ul> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>fix: save multi_use to the DB for OOB invitations #2694 frostyfrog</li> <li>Connection and DIDX Problem Reports #2653 usingtechnology</li> <li> <p>Feat: DIDX Implicit Request auto-accept and Delete OOB Invitation related records #2642 shaangill025</p> </li> <li> <p>DID Peer and DID Resolver Updates and Fixes</p> </li> <li>Integration test for did:peer #2713 ianco</li> <li>Feature/emit did peer 4 #2696 Jsyro</li> <li>did peer 4 resolution #2692 Jsyro</li> <li>Emit did:peer:2 for didexchange #2687 Jsyro</li> <li>Add did web method type as a default option #2684 PatStLouis</li> <li>feat: add did:jwk resolver #2645 dbluhm</li> <li> <p>feat: support resolving did:peer:1 received in did exchange #2611 dbluhm</p> </li> <li> <p>Ledger Agnostic AnonCreds RS Changes</p> </li> <li>Anoncreds revoke and publish-revocations endorsement #2782 jamshale</li> <li>Upgrade anoncreds to version 0.2.0-dev11 #2763 jamshale</li> <li>Update anoncreds to 0.2.0-dev10 #2758 jamshale</li> <li>Anoncreds - Cred Def and Revocation Endorsement #2752 jamshale</li> <li>Upgrade anoncreds to 0.2.0-dev9 #2741 jamshale</li> <li>Upgrade anoncred-rs to version 0.2.0-dev8 #2734 jamshale</li> <li>Upgrade anoncreds to 0.2.0.dev7 #2719 jamshale</li> <li>Improve api documentation and error handling #2690 jamshale</li> <li>Add unit tests for anoncreds revocation #2688 jamshale</li> <li>Return 404 when schema not found #2683 jamshale</li> <li>Anoncreds - Add unit testing #2672 jamshale</li> <li>Additional anoncreds integration tests  AnonCreds #2660 ianco</li> <li>Update integration tests for anoncreds-rs  AnonCreds #2651 ianco</li> <li>Initial migration of anoncreds revocation code  AnonCreds #2643 ianco</li> <li>Integrate Anoncreds rs into credential and presentation endpoints  AnonCreds #2632 ianco</li> <li> <p>Initial code migration from anoncreds-rs branch  AnonCreds #2596 ianco</p> </li> <li> <p>Hyperledger Indy ledger related updates and fixes</p> </li> <li>Add known issues section to Multiledger.md documentation #2788 esune</li> <li>fix: update constants in TransactionRecord #2698 amanji</li> <li>Cache TAA by wallet name #2676 jamshale</li> <li> <p>Fix: RevRegEntry Transaction Endorsement  0.11.0 #2558 shaangill025</p> </li> <li> <p>JSON-LD Verifiable Credential/DIF Presentation Exchange updates</p> </li> <li>Revert profile injection for VcLdpManager on vc-api endpoints #2794 PatStLouis</li> <li>Add cached copy of BBS v1 context #2749 andrewwhitehead</li> <li>Update BBS+ context to bypass redirections #2739 swcurran</li> <li>feat: make VcLdpManager pluggable #2706 dbluhm</li> <li>fix: minor type hint corrections for VcLdpManager #2704 dbluhm</li> <li>Remove if condition which checks if the credential.type array is equal to 1 #2670 PatStLouis</li> <li>Feature Suggestion: Include a Reason When Constraints Cannot Be Applied #2630 Ennovate-com</li> <li> <p>refactor: make ldp_vc logic reusable #2533 dbluhm</p> </li> <li> <p>Credential Exchange (Issue, Present) Updates</p> </li> <li>Remove exception on connectionless presentation problem report handler #2723 loneil</li> <li>Ensure \"preserve_exchange_records\" flags are set. #2664 usingtechnology</li> <li>Slight improvement to credx proof validation error message #2655 ianco</li> <li> <p>Add ConnectionProblemReport handler #2600 usingtechnology</p> </li> <li> <p>Multitenancy Updates and Fixes</p> </li> <li>feature/per tenant settings #2790 amanji</li> <li> <p>Improve Per Tenant Logging: Fix issues around default log file path #2659 shaangill025</p> </li> <li> <p>Other Fixes, Demo, DevContainer and Documentation Fixes</p> </li> <li>Demo description of reuse in establishing a connection #2787 swcurran</li> <li>Reorganize the ACA-Py Documentation Files #2765 swcurran</li> <li>Tweaks to MD files to enable aca-py.org publishing #2771 swcurran</li> <li>Update devcontainer documentation #2729 jamshale</li> <li>Update the SupportedRFCs Document to be up to date #2722 swcurran</li> <li>Fix incorrect Sphinx search library version reference #2716 swcurran</li> <li>Update RTD requirements after security vulnerability recorded #2712 swcurran</li> <li>Update legacy bcgovimages references. #2700 WadeBarnes</li> <li>fix: link to raw content change from master to main #2663 Ennovate-com</li> <li>fix: open-api generator script #2661 dbluhm</li> <li> <p>Update the ReadTheDocs config in case we do another 0.10.x release #2629 swcurran</p> </li> <li> <p>Dependencies and Internal Updates</p> </li> <li>Change middleware registration order #2796 PatStLouis</li> <li>Bump pyld version to 2.0.4 #2795 PatStLouis</li> <li>Revert profile inject #2789 jamshale</li> <li>Move emit events to profile and delay sending until after commit #2760 ianco</li> <li>fix: partial revert of ConnRecord schema change  1.0.0 #2746 dbluhm</li> <li>chore(deps): Bump aiohttp from 3.9.1 to 3.9.2  dependencies #2745 dependabot bot</li> <li>bump pydid to v 0.4.3 #2737 PatStLouis</li> <li>Fix subwallet record removal #2721 andrewwhitehead</li> <li>chore(deps): Bump jinja2 from 3.1.2 to 3.1.3  dependencies #2707 dependabot bot</li> <li>feat: inject profile #2705 dbluhm</li> <li>Remove tiny-vim from being added to the container image to reduce reported vulnerabilities from scanning #2699 swcurran</li> <li>chore(deps): Bump jwcrypto from 1.5.0 to 1.5.1  dependencies #2689 dependabot bot</li> <li>Update dependencies #2686 andrewwhitehead</li> <li>Fix: Change To Use Timezone Aware UTC datetime #2679 Ennovate-com</li> <li>fix: update broken demo dependency #2638 mrkaurelius</li> <li>Bump cryptography from 41.0.5 to 41.0.6  dependencies #2636 dependabot bot</li> <li> <p>Bump aiohttp from 3.8.6 to 3.9.0  dependencies #2635 dependabot bot</p> </li> <li> <p>CI/CD, Testing, and Developer Tools/Productivity Updates</p> </li> <li>Fix deprecation warnings #2756 ff137</li> <li>chore(deps): Bump the all-actions group with 10 updates  dependencies #2784 dependabot bot</li> <li>Add Dependabot configuration #2783 WadeBarnes</li> <li>Implement B006 rule #2775 jamshale</li> <li>\u2b06\ufe0f Upgrade pytest to 8.0 #2773 ff137</li> <li>\u2b06\ufe0f Update pytest-asyncio to 0.23.4 #2764 ff137</li> <li>Remove asynctest dependency and fix \"coroutine not awaited\" warnings #2755 ff137</li> <li>Fix pytest collection errors when anoncreds package is not installed #2750 andrewwhitehead</li> <li>chore: pin black version #2747 dbluhm</li> <li>Tweak scope of GHA integration tests #2662 ianco</li> <li> <p>Update snyk workflow to execute on Pull Request #2658 usingtechnology</p> </li> <li> <p>Release management pull requests</p> </li> <li>0.12.0rc1 #2800 swcurran</li> <li>0.12.0rc1 #2799 swcurran</li> <li>0.12.0rc0 #2732 swcurran</li> </ul>"},{"location":"CHANGELOG/#0110","title":"0.11.0","text":""},{"location":"CHANGELOG/#november-24-2023","title":"November 24, 2023","text":"<p>Release 0.11.0 is a relatively large release of new features, fixes, and internal updates. 0.11.0 is planned to be the last significant update before we begin the transition to using the ledger agnostic AnonCreds Rust in a release that is expected to bring Admin/Controller API changes. We plan to do patches to the 0.11.x branch while the transition is made to using [Anoncreds Rust].</p> <p>An important addition to ACA-Py is support for signing and verifying SD-JWT verifiable credentials. We expect this to be the first of the changes to extend ACA-Py to support OpenID4VC protocols.</p> <p>This release and Release 0.10.5 contain a high priority fix to correct an issue with the handling of the JSON-LD presentation verifications, where the status of the verification of the <code>presentation.proof</code> in the Verifiable Presentation was not included when determining the verification value (<code>true</code> or <code>false</code>) of the overall presentation. A forthcoming security advisory will cover the details. Anyone using JSON-LD presentations is recommended to upgrade to one of these versions of ACA-Py as soon as possible.</p> <p>In the CI/CD realm, substantial changes were applied to the source base in switching from:</p> <ul> <li><code>pip</code> to Poetry for packaging and dependency management,</li> <li>Flake8 to Ruff for linting,</li> <li><code>asynctest</code> to <code>IsolatedAsyncioTestCase</code> and <code>AsyncMock</code> objects now included in Python's builtin <code>unittest</code> package for unit testing.</li> </ul> <p>These are necessary and important modernization changes, with the latter two triggering many (largely mechanical) changes to the codebase.</p>"},{"location":"CHANGELOG/#0110-breaking-changes","title":"0.11.0 Breaking Changes","text":"<p>In addition to the impacts of the change for developers in switching from <code>pip</code> to Poetry, the only significant breaking change is the (overdue) transition of ACA-Py to always use the new DIDComm message type prefix, changing the DID Message prefix from the old hardcoded <code>did:sov:BzCbsNYhMrjHiqZDTUASHg;spec</code> to the new hardcoded <code>https://didcomm.org</code> value, and using the new DIDComm MIME type in place of the old. The vast majority (all?) Aries deployments have long since been updated to accept both values, so this change just forces the use of the newer value in sending messages. In updating this, we retained the old configuration parameters most deployments were using (<code>--emit-new-didcomm-prefix</code> and <code>--emit-new-didcomm-mime-type</code>) but updated the code to set the configuration parameters to <code>true</code> even if the parameters were not set. See [PR #2517].</p> <p>The JSON-LD verifiable credential handling of JSON-LD contexts has been updated to pre-load the base contexts into the repository code so they are not fetched at run time. This is a security best practice for JSON-LD, and prevents errors in production when, from time to time, the JSON-LD contexts are unavailable because of outages of the web servers where they are hosted. See [PR #2587].</p> <p>A Problem Report message is now sent when a request for a credential is received and there is no associated Credential Exchange Record. This may happen, for example, if an issuer decides to delete a Credential Exchange Record that has not be answered for a long time, and the holder responds after the delete. See [PR #2577].</p>"},{"location":"CHANGELOG/#0110-categorized-list-of-pull-requests","title":"0.11.0 Categorized List of Pull Requests","text":"<ul> <li>DIDComm Messaging Improvements/Fixes</li> <li>Change arg_parse to always set --emit-new-didcomm-prefix and --emit-new-didcomm-mime-type to true #2517 swcurran</li> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>Goal and Goal Code in invitation URL. #2591 usingtechnology</li> <li>refactor: use did-peer-2 instead of peerdid #2561 dbluhm</li> <li>Fix: Problem Report Before Exchange Established #2519 Ennovate-com</li> <li>fix: issue #2434: Change DIDExchange States to Match rfc160 #2461 anwalker293</li> <li>DID Peer and DID Resolver Updates and Fixes</li> <li>fix: unique ids for services in legacy peer #2476 dbluhm</li> <li>peer did \u2154 resolution  enhancement #2472 Jsyro</li> <li>feat: add timeout to did resolver resolve method #2464 dbluhm</li> <li>ACA-Py as a DIDComm Mediator Updates and Fixes</li> <li>fix: routing behind mediator #2536 dbluhm</li> <li>fix: mediation routing keys as did key #2516 dbluhm</li> <li>refactor: drop mediator_terms and recipient_terms #2515 dbluhm</li> <li>Fixes to Upgrades</li> <li>\ud83d\udc1b fix wallet_update when only extra_settings requested #2612 ff137</li> <li>Hyperledger Indy ledger related updates and fixes</li> <li>fix: taa rough timestamp timezone from datetime #2554 dbluhm</li> <li>\ud83c\udfa8 clarify LedgerError message when TAA is required and not accepted #2545 ff137</li> <li>Feat: Upgrade from tags and fix issue with legacy IssuerRevRegRecords [&lt;=v0.5.2] #2486 shaangill025</li> <li>Bugfix: Issue with write ledger pool when performing Accumulator sync #2480 shaangill025</li> <li>Issue #2419 InvalidClientTaaAcceptanceError time too precise error if container timezone is not UTC #2420 Ennovate-com</li> <li>OpenID4VC / SD-JWT Updates</li> <li>chore: point to official sd-jwt lib release #2573 dbluhm</li> <li>Feat/sd jwt implementation #2487 cjhowland</li> <li>JSON-LD Verifiable Credential/Presentation updates</li> <li>fix: report presentation result #2615 dbluhm</li> <li>Fix Issue #2589 TypeError When There Are No Nested Requirements #2590 Ennovate-com</li> <li>feat: use a local static cache for commonly used contexts #2587 chumbert</li> <li>Issue #2488 KeyError raised when Subject ID is not a URI #2490 Ennovate-com</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Default connection_id to None to account for Connectionless Proofs #2605 popkinj</li> <li>Send Problem report when CredEx not found #2577 usingtechnology</li> <li>fix: clean up requests and invites #2560 dbluhm</li> <li>Multitenancy Updates and Fixes</li> <li>Feat: Support subwallet upgradation using the Upgrade command #2529 shaangill025</li> <li>Other Fixes, Demo, DevContainer and Documentation Fixes</li> <li>fix: wallet type help text out of date #2618 dbluhm</li> <li>fix: typos #2614 omahs</li> <li>black formatter extension configuration update #2603 usingtechnology</li> <li>Update Devcontainer pytest ruff black #2602 usingtechnology</li> <li>Issue 2570 devcontainer ruff, black and pytest #2595 usingtechnology</li> <li>chore: correct type hints on base record #2604 dbluhm</li> <li>Playground needs optionally external network #2564 usingtechnology</li> <li>Issue 2555 playground scripts readme #2563 usingtechnology</li> <li>Update demo/playground scripts #2562 usingtechnology</li> <li>Update .readthedocs.yaml #2548 swcurran</li> <li>Update .readthedocs.yaml #2547 swcurran</li> <li>fix: correct minor typos #2544 Ennovate-com</li> <li>Update steps for Manually Creating Revocation Registries #2491 WadeBarnes</li> <li>Dependencies and Internal Updates</li> <li>chore: bump pydid version #2626 dbluhm</li> <li>chore: dependency updates #2565 dbluhm</li> <li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7  dependencies #2552 dependabot bot</li> <li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7 in /demo/playground/scripts  dependencies #2551 dependabot bot</li> <li>chore: update pydid #2527 dbluhm</li> <li>chore(deps): Bump urllib3 from 2.0.5 to 2.0.6  dependencies #2525 dependabot bot</li> <li>chore(deps): Bump urllib3 from 2.0.2 to 2.0.6 in /demo/playground/scripts  dependencies #2524 dependabot bot</li> <li>Avoid multiple open wallet connections #2521 andrewwhitehead</li> <li>Remove unused dependencies #2510 andrewwhitehead</li> <li>Use correct rust log level in dockerfiles #2499 loneil</li> <li>fix: run tests script copying local env #2495 dbluhm</li> <li>Update devcontainer to read version from aries-cloudagent package #2483 usingtechnology</li> <li>Update Python image version to 3.9.18 #2456 WadeBarnes</li> <li>Remove old routing protocol code #2466 dbluhm</li> <li>CI/CD, Testing, and Developer Tools/Productivity Updates</li> <li>fix: drop asynctest  0.11.0 #2566 dbluhm</li> <li>Dockerfile.indy - Include aries_cloudagent code into build #2584 usingtechnology</li> <li>fix: version should be set by pyproject.toml #2471 dbluhm</li> <li>chore: add black back in as a dev dep #2465 dbluhm</li> <li>Swap out flake8 in favor of Ruff #2438 dbluhm</li> <li> </li> <li>Release management pull requests</li> <li>0.11.0 #2627 swcurran</li> <li>0.11.0rc2 #2613 swcurran</li> <li>0.11.0-rc1 #2576 swcurran</li> <li>0.11.0-rc0 #2575 swcurran</li> </ul>"},{"location":"CHANGELOG/#2289-migrate-to-poetry-2436-gavinok","title":"2289 Migrate to Poetry #2436 Gavinok","text":""},{"location":"CHANGELOG/#0105","title":"0.10.5","text":""},{"location":"CHANGELOG/#november-21-2023","title":"November 21, 2023","text":"<p>Release 0.10.5 is a high priority patch release to correct an issue with the handling of the JSON-LD presentation verifications, where the status of the verification of the <code>presentation.proof</code> in the Verifiable Presentation was not included when determining the verification value (<code>true</code> or <code>false</code>) of the overall presentation. A forthcoming security advisory will cover the details.</p> <p>Anyone using JSON-LD presentations is recommended to upgrade to this version of ACA-Py as soon as possible.</p>"},{"location":"CHANGELOG/#0105-categorized-list-of-pull-requests","title":"0.10.5 Categorized List of Pull Requests","text":"<ul> <li>JSON-LD Credential Exchange (Issue, Present) Updates</li> <li>fix(backport): report presentation result #2622 dbluhm</li> <li>Release management pull requests</li> <li>0.10.5 #2623 swcurran</li> </ul>"},{"location":"CHANGELOG/#0104","title":"0.10.4","text":""},{"location":"CHANGELOG/#october-9-2023","title":"October 9, 2023","text":"<p>Release 0.10.4 is a patch release to correct an issue with the handling of <code>did:key</code> routing keys in some mediator scenarios, notably with the use of [Aries Framework Kotlin]. See the details in the PR and [Issue #2531 Routing for agents behind a aca-py based mediator is broken].</p> <p>Thanks to codespree for raising the issue and providing the fix.</p> <p>Aries Framework Kotlin</p>"},{"location":"CHANGELOG/#0104-categorized-list-of-pull-requests","title":"0.10.4 Categorized List of Pull Requests","text":"<ul> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>fix: routing behind mediator #2536 dbluhm</li> <li>Release management pull requests</li> <li>0.10.4 #2539 swcurran</li> </ul>"},{"location":"CHANGELOG/#0103","title":"0.10.3","text":""},{"location":"CHANGELOG/#september-29-2023","title":"September 29, 2023","text":"<p>Release 0.10.3 is a patch release to add an upgrade process for very old versions of Aries Cloud Agent Python (circa 0.5.2). If you have a long time deployment of an issuer that uses revocation, this release could correct internal data (tags in secure storage) related to revocation registries. Details of the about the triggering problem can be found in [Issue #2485].</p> <p>The upgrade is applied by running the following command for the ACA-Py instance to be upgraded:</p> <p><code>./scripts/run_docker upgrade --force-upgrade --named-tag fix_issue_rev_reg</code></p>"},{"location":"CHANGELOG/#0103-categorized-list-of-pull-requests","title":"0.10.3 Categorized List of Pull Requests","text":"<ul> <li>Credential Exchange (Issue, Present) Updates</li> <li>Feat: Upgrade from tags and fix issue with legacy IssuerRevRegRecords [&lt;=v0.5.2] #2486 shaangill025</li> <li>Release management pull requests</li> <li>0.10.3 #2522 swcurran</li> </ul>"},{"location":"CHANGELOG/#0102","title":"0.10.2","text":""},{"location":"CHANGELOG/#september-22-2023","title":"September 22, 2023","text":"<p>Release 0.10.2 is a patch release for 0.10.1 that addresses three specific regressions found in deploying Release 0.10.1. The regressions are to fix:</p> <ul> <li>An ACA-Py instance upgraded to 0.10.1 that had an existing connection to another Aries agent where the connection has both an <code>http</code> and <code>ws</code> (websocket) service endpoint with the same ID cannot message that agent. A scenario is an ACA-Py issuer connecting to an Endorser with both <code>http</code> and <code>ws</code> service endpoints. The updates made in 0.10.1 to improve ACA-Py DID resolution did not account for this scenario and needed a tweak to work ([Issue #2474], [PR #2475]).</li> <li>The \"fix revocation registry\" endpoint used to fix scenarios an Issuer's local revocation registry state is out of sync with the ledger was broken by some code being added to support a single ACA-Py instance writing to different ledgers ([Issue #2477], [PR #2480]).</li> <li>The version of the PyDID library we were using did not handle some unexpected DID resolution use cases encountered with mediators. The PyDID library version dependency was updated in [PR #2500].</li> </ul>"},{"location":"CHANGELOG/#0102-categorized-list-of-pull-requests","title":"0.10.2 Categorized List of Pull Requests","text":"<ul> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>LegacyPeerDIDResolver: erroneously assigning same ID to multiple services #2475 dbluhm</li> <li>fix: update pydid #2500 dbluhm</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Bugfix: Issue with write ledger pool when performing Accumulator sync #2480 shaangill025</li> <li>Release management pull requests</li> <li>0.10.2 #2509 swcurran</li> <li>0.10.2-rc0 #2484 swcurran</li> <li>0.10.2 Patch Release - fix issue #2475, #2477 #2482 shaangill025</li> </ul>"},{"location":"CHANGELOG/#0101","title":"0.10.1","text":""},{"location":"CHANGELOG/#august-29-2023","title":"August 29, 2023","text":"<p>Release 0.10.1 contains a breaking change, an important fix for a regression introduced in 0.8.2 that impacts certain deployments, and a number of fixes and updates. Included in the updates is a significant internal reorganization of the DID and connection management code that was done to enable more flexible uses of different DID Methods, such as being able to use <code>did:web</code> DIDs for DIDComm messaging connections. The work also paves the way for coming updates related to support for <code>did:peer</code> DIDs for DIDComm. For details on the change see [PR #2409], which includes some of the best pull request documentation ever created.</p> <p>Release 0.10.1 has the same contents as 0.10.0. An error on PyPi prevented the 0.10.0 release from being properly uploaded because of an existing file of the same name. We immediately released 0.10.1 as a replacement.</p> <p>The regression fix is for ACA-Py deployments that use multi-use invitations but do NOT use the <code>--auto-accept-connection-requests</code> flag/processing. A change in 0.8.2 (PR [#2223]) suppressed an extra webhook event firing during the processing after receiving a connection request. An unexpected side effect of that change was that the subsequent webhook event also did not fire, and as a result, the controller did not get any event signalling a new connection request had been received via the multi-use invitation. The update in this release ensures the proper event fires and the controller receives the webhook.</p> <p>See below for the breaking changes and a categorized list of the pull requests included in this release.</p> <p>Updates in the CI/CD area include adding the publishing of a <code>nightly</code> container image that includes any changes in the main branch since the last <code>nightly</code> was published. This allows getting the \"latest and greatest\" code via a container image vs. having to install ACA-Py from the repository. In addition, Snyk scanning was added to the CI pipeline, and Indy SDK tests were removed from the pipeline.</p>"},{"location":"CHANGELOG/#0101-breaking-changes","title":"0.10.1 Breaking Changes","text":"<p>[#2352] is a breaking change related to the storage of presentation exchange records in ACA-Py. In previous releases, presentation exchange protocol state data records were retained in ACA-Py secure storage after the completion of protocol instances. With this release the default behavior changes to deleting those records by default, unless the <code>----preserve-exchange-records</code> flag is set in the configuration. This extends the use of that flag that previously applied only to issue credential records. The extension matches the initial intention of the flag--that it cover both issue credential and present proof exchanges. The \"best practices\" for ACA-Py is that the controller (business logic) store any long-lasting business information needed for the service that is using the Aries Agent, and ACA-Py storage should be used only for data necessary for the operation of the agent. In particular, protocol state data should be held in ACA-Py only as long as the protocol is running (as it is needed by ACA-Py), and once a protocol instance completes, the controller should extract and store the business information from the protocol state before it is deleted from ACA-Py storage.</p>"},{"location":"CHANGELOG/#0100-categorized-list-of-pull-requests","title":"0.10.0 Categorized List of Pull Requests","text":"<ul> <li>DIDComm Messaging Improvements/Fixes</li> <li>fix: outbound send status missing on path #2393 dbluhm</li> <li>fix: keylist update response race condition #2391 dbluhm</li> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>fix: handle stored afgo and findy docs in corrections #2450 dbluhm</li> <li>chore: relax connections filter DID format #2451 chumbert</li> <li>fix: ignore duplicate record errors on add key #2447 dbluhm</li> <li>fix: ignore duplicate record errors on add key #2447 dbluhm</li> <li>fix: more diddoc corrections #2446 dbluhm</li> <li>feat: resolve connection targets and permit connecting via public DID #2409 dbluhm</li> <li>feat: add legacy peer did resolver #2404 dbluhm</li> <li>Fix: Ensure event/webhook is emitted for multi-use invitations #2413 esune</li> <li>feat: add DID Exchange specific problem reports and reject endpoint #2394 dbluhm</li> <li>fix: additional tweaks for did:web and other methods as public DIDs #2392 dbluhm</li> <li>Fix empty ServiceDecorator in OobRecord causing 422 Unprocessable Entity Error #2362 ff137</li> <li>Feat: Added support for Ed25519Signature2020 signature type and Ed25519VerificationKey2020 #2241 dkulic</li> <li>Upgrading to Aries Askar Updates</li> <li>Add symlink to /home/indy/.indy_client for backwards compatibility #2443 esune</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>fix: ensure request matches offer in JSON-LD exchanges, if sent #2341 dbluhm</li> <li>BREAKING Extend --preserve-exchange-records to include Presentation Exchange. #2352 usingtechnology</li> <li>Correct the response type in send_rev_reg_def #2355 ff137</li> <li>Multitenancy Updates and Fixes</li> <li>Multitenant check endorser_info before saving #2395 usingtechnology</li> <li>Feat: Support Selectable Write Ledger #2339 shaangill025</li> <li>Other Fixes, Demo, and Documentation Fixes</li> <li>Redis Plugins [redis_cache &amp; redis_queue] documentation and docker related updates #1937 shaangill025</li> <li>Chore: fix marshmallow warnings #2398 ff137</li> <li>Upgrade pre-commit and flake8 dependencies; fix flake8 warnings #2399 ff137</li> <li>Corrected typo on mediator invitation configuration argument #2365 jorgefl0</li> <li>Add workaround for ARM based macs #2313 finnformica</li> <li>Dependencies and Internal Updates</li> <li>chore(deps): Bump certifi from 2023.5.7 to 2023.7.22 in /demo/playground/scripts dependencies #2354 dependabot bot</li> <li>CI/CD and Developer Tools/Productivity Updates</li> <li>Fix for nightly tests failing on Python 3.10 #2435 Gavinok</li> <li>Don't run Snyk on forks #2429 ryjones</li> <li>Issue #2250 Nightly publish workflow #2421 Gavinok</li> <li>Enable Snyk scanning #2418 ryjones</li> <li>Remove Indy tests from workflows #2415 dbluhm</li> <li>Release management pull requests</li> <li>0.10.1 #2454 swcurran</li> <li>0.10.0 #2452 swcurran</li> <li>0.10.0-rc2 #2448 swcurran</li> <li>0.10.0-rc1 #2442 swcurran</li> <li>0.10.0-rc0 #2414 swcurran</li> </ul>"},{"location":"CHANGELOG/#0100","title":"0.10.0","text":""},{"location":"CHANGELOG/#august-29-2023_1","title":"August 29, 2023","text":"<p>Release 0.10.1 has the same contents as 0.10.0. An error on PyPi prevented the 0.10.0 release from being properly uploaded because of an existing file of the same name. We immediately released 0.10.1 as a replacement.</p>"},{"location":"CHANGELOG/#090","title":"0.9.0","text":""},{"location":"CHANGELOG/#july-24-2023","title":"July 24, 2023","text":"<p>Release 0.9.0 is an important upgrade that changes (PR [#2302]) the dependency on the now archived Hyperledger Ursa project to its updated, improved replacement, AnonCreds CL-Signatures. This important change is ONLY available when using Aries Askar as the wallet type, which brings in both [Indy VDR] and the CL-Signatures via the latest version of CredX from the indy-shared-rs repository. The update is NOT available to those that are using the Indy SDK. All new deployments of ACA-Py SHOULD use Aries Askar. Further, we strongly recommend that all deployments using the Indy SDK with ACA-Py upgrade their installation to use Aries Askar and the related components using the migration scripts available. An Indy SDK to Askar migration document added to the aca-py.org documentation site, and a deprecation warning added to the ACA-Py startup.</p> <p>The second big change in this release is that we have upgraded the primary Python version from 3.6 to 3.9 (PR [#2247]). In this case, primary means that Python 3.9 is used to run the unit and integration tests on all Pull Requests. We also do nightly runs of the main branch using Python 3.10. As of this release we have dropped Python 3.6, 3.7 and 3.8, and introduced new dependencies that are not supported in those versions of Python. For those that use the published ACA-Py container images, the upgrade should be easily handled. If you are pulling ACA-Py into your own image, or a non-containerized environment, this is a breaking change that you will need to address.</p> <p>Please see the next section for all breaking changes, and the subsequent section for a categorized list of all pull requests in this release.</p>"},{"location":"CHANGELOG/#breaking-changes","title":"Breaking Changes","text":"<p>In addition to the breaking Python 3.6 to 3.9 upgrade, there are two other breaking changes that may impact some deployments.</p> <p>[#2034] allows for additional flexibility in using public DIDs in invitations, and adds a restriction that \"implicit\" invitations must be proactively enabled using a flag (<code>--requests-through-public-did</code>). Previously, such requests would always be accepted if <code>--auto-accept</code> was enabled, which could lead to unexpected connections being established.</p> <p>[#2170] is a change to improve message handling in the face of delivery errors when using a persistent queue implementation such as the ACA-Py Redis Plugin. If you are using the Redis plugin, you MUST upgrade to Redis Plugin Release 0.1.0 in conjunction with deploying this ACA-Py release. For those using their own persistent queue solution, see the PR [#2170] comments for information about changes you might need to make to your deployment.</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests","title":"Categorized List of Pull Requests","text":"<ul> <li>DIDComm Messaging Improvements/Fixes</li> <li>BREAKING: feat: get queued outbound message in transport handle message #2170 dbluhm</li> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>Allow any did to be public #2295 mkempa</li> <li>Feat: Added support for Ed25519Signature2020 signature type and Ed25519VerificationKey2020 #2241 dkulic</li> <li>Add Goal and Goal Code to OOB and DIDex Request #2294 usingtechnology</li> <li>Fix routing in set public did #2288 mkempa  - Fix: Do not replace public verkey on mediator #2269 mkempa  - BREAKING: Allow multi-use public invites and public invites with metadata #2034 mepeltier</li> <li>fix: public did mediator routing keys as did keys #1977 dbluhm</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Add revocation registry rotate to faber demo #2333 usingtechnology</li> <li>Update to indy-credx 1.0 #2302 andrewwhitehead</li> <li>feat(anoncreds): Implement automated setup of revocation #2292 dbluhm</li> <li>fix: schema class can set Meta.unknown #1885 dbluhm</li> <li>Respect auto-verify-presentation flag in present proof v1 and v2 #2097 dbluhm</li> <li>Feature: JWT Sign and Verify Admin Endpoints with DID Support #2300 burdettadam</li> <li>Multitenancy Updates and Fixes</li> <li>Fix: Track endorser and author roles in per-tenant settings #2331 shaangill025</li> <li>Added base wallet provisioning details to Multitenancy.md #2328 esune</li> <li>Other Fixes, Demo, and Documentation Fixes</li> <li>Add more context to the ACA-Py Revocation handling documentation #2343 swcurran</li> <li>Document the Indy SDK to Askar Migration process #2340 swcurran</li> <li>Add revocation registry rotate to faber demo #2333 usingtechnology</li> <li>chore: add indy deprecation warnings #2332 dbluhm</li> <li>Fix alice/faber demo execution #2305 andrewwhitehead</li> <li>Add .indy_client folder to Askar only image. #2308 WadeBarnes</li> <li>Add build step for indy-base image in run_demo #2299 usingtechnology</li> <li>Webhook over websocket clarification #2287 dbluhm</li> <li>ACA-Py Deployment Upgrade Changes</li> <li>Add Explicit/Offline marking mechanism for Upgrade #2204 shaangill025</li> <li>Plugin Handling Updates</li> <li>Feature: Add the ability to deny specific plugins from loading  0.7.4 #1737 frostyfrog</li> <li>Dependencies and Internal Updates</li> <li>upgrade pyjwt to latest; introduce leeway to jwt.decodet #2335 ff137</li> <li>upgrade requests to latest #2336 ff137</li> <li>upgrade packaging to latest #2334 ff137</li> <li>chore: update PyYAML #2329 dbluhm</li> <li>chore(deps): Bump aiohttp from 3.8.4 to 3.8.5 in /demo/playground/scripts dependencies #2325 dependabot bot</li> <li>\u2b06\ufe0f upgrade marshmallow to latest #2322 ff137</li> <li>fix: use python 3.9 in run_docker #2291 dbluhm</li> <li>BREAKING!: drop python 3.6 support #2247 dbluhm</li> <li>Minor revisions to the README.md and DevReadMe.md #2272 swcurran</li> <li>ACA-Py Administrative Updates</li> <li>Updating Maintainers list to be accurate and using the TOC format #2258 swcurran</li> <li>CI/CD and Developer Tools/Productivity Updates</li> <li>Cancel in-progress workflows when PR is updated #2303 andrewwhitehead</li> <li>ci: add gha for pr-tests #2058 dbluhm</li> <li>Add devcontainer for ACA-Py #2267 usingtechnology</li> <li>Docker images and GHA for publishing images  help wanted #2076 dbluhm</li> <li>ci: test additional versions of python nightly #2059 dbluhm</li> <li>Release management pull requests</li> <li>0.9.0 #2344 swcurran</li> <li>0.9.0-rc0 #2338 swcurran</li> </ul>"},{"location":"CHANGELOG/#082","title":"0.8.2","text":""},{"location":"CHANGELOG/#june-29-2023","title":"June 29, 2023","text":"<p>Release 0.8.2 contains a number of minor fixes and updates to ACA-Py, including the correction of a regression in Release 0.8.0 related to the use of plugins (see [#2255]). Highlights include making it easier to use tracing in a development environment to collect detailed performance information about what is going in within ACA-Py.</p> <p>This release pulls in indy-shared-rs Release 3.3 which fixes a serious issue in AnonCreds verification, as described in issue [#2036], where the verification of a presentation with multiple revocable credentials fails when using Aries Askar and the other shared components. This issue occurs only when using Aries Askar and indy-credx Release 3.3.</p> <p>An important new feature in this release is the ability to set some instance configuration settings at the tenant level of a multi-tenant deployment. See PR [#2233].</p> <p>There are no breaking changes in this release.</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_1","title":"Categorized List of Pull Requests","text":"<ul> <li>Connections Fixes/Updates</li> <li>Resolve definitions.py fix to fix backwards compatibility break in plugins #2255 usingtechnology</li> <li>Add support for JsonWebKey2020 for the connection invitations #2173 dkulic</li> <li>fix: only cache completed connection targets #2240 dbluhm</li> <li>Connection target should not be limited only to indy dids #2229 dkulic</li> <li>Disable webhook trigger on initial response to multi-use connection invitation #2223 esune</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Pass document loader to jsonld.expand #2175 andrewwhitehead</li> <li>Multi-tenancy fixes/updates</li> <li>Allow Configuration Settings on a per-tenant basis #2233 shaangill025</li> <li>stand up multiple agents (single and multi) for local development and testing #2230 usingtechnology</li> <li>Multi-tenant self-managed mediation verkey lookup #2232 usingtechnology</li> <li>fix: route multitenant connectionless oob invitation #2243 TimoGlastra</li> <li>Fix multitenant/mediation in demo #2075 ianco</li> <li>Other Bug and Documentation Fixes</li> <li>Assign ~thread.thid with thread_id value #2261 usingtechnology</li> <li>Fix: Do not replace public verkey on mediator #2269 mkempa</li> <li>Provide an optional Profile to the verification key strategy #2265 yvgny</li> <li>refactor: Extract verification method ID generation to a separate class #2235 yvgny</li> <li>Create .readthedocs.yaml file #2268 swcurran</li> <li>feat(did creation route): reject unregistered did methods #2262 chumbert</li> <li>./run_demo performance -c 1 --mediation --timing --trace-log #2245 usingtechnology</li> <li>Fix formatting and grammatical errors in different readme's #2222 ff137</li> <li>Fix broken link in README #2221 ff137</li> <li>fix: run only on main, forks ok #2166 anwalker293</li> <li>Update Alice Wants a JSON-LD Credential to fix invocation #2219 swcurran</li> <li>Dependencies and Internal Updates</li> <li>Bump requests from 2.30.0 to 2.31.0 in /demo/playground/scripts dependenciesPull requests that update a dependency file #2238 dependabot bot</li> <li>Upgrade codegen tools in scripts/generate-open-api-spec and publish Swagger 2.0 and OpenAPI 3.0 specs #2246 ff137</li> <li>ACA-Py Administrative Updates</li> <li>Propose adding Jason Sherman usingtechnology as a Maintainer #2263 swcurran</li> <li>Updating Maintainers list to be accurate and using the TOC format #2258 swcurran</li> <li>Message Tracing/Timing Updates</li> <li>Add updated ELK stack for demos. #2236 usingtechnology</li> <li>Release management pull requests</li> <li>0.8.2 #2285 swcurran</li> <li>0.8.2-rc2 #2284 swcurran</li> <li>0.8.2-rc1 #2282 swcurran</li> <li>0.8.2-rc0 #2260 swcurran</li> </ul>"},{"location":"CHANGELOG/#081","title":"0.8.1","text":""},{"location":"CHANGELOG/#april-5-2023","title":"April 5, 2023","text":"<p>Version 0.8.1 is an urgent update to Release 0.8.0 to address an inability to execute the <code>upgrade</code> command. The <code>upgrade</code> command is needed for 0.8.0 Pull Request [#2116] - \"UPGRADE: Fix multi-use invitation performance\", which is useful for (at least) deployments of ACA-Py as a mediator. In the release, the upgrade process is revamped, and documented in Upgrading ACA-Py.</p> <p>Key points about upgrading for those with production, pre-0.8.1 ACA-Py deployments:</p> <ul> <li>Upgrades now happen automatically on startup, when needed.</li> <li>The version of the last executed upgrade, even if it is a \"no change\" upgrade,   is put into secure storage and is used to detect when future upgrades are needed.</li> <li>Upgrades are needed when the running version is greater than the version is     secure storage.</li> <li>If you have an existing, pre-0.8.1 deployment with many connection records, there may be a delay in starting as an upgrade will be run that loads and saves every connection record, updating the data in the record in the process.</li> <li>A mechanism is to be added (see Issue #2201) for preventing an upgrade   running if it should not be run automatically, and requires using the   <code>upgrade</code> command. To date, there has been no need for this feature.</li> <li>See the Upgrading ACA-Py document for more details.</li> </ul>"},{"location":"CHANGELOG/#postgres-support-with-aries-askar","title":"Postgres Support with Aries Askar","text":"<p>Recent changes to Aries Askar have resulted in Askar supporting Postgres version 11 and greater. If you are on Postgres 10 or earlier and want to upgrade to use Askar, you must migrate your database to Postgres 10.</p> <p>We have also noted that in some container orchestration environments such as Red Hat's OpenShift and possibly other Kubernetes distributions, Askar using Postgres versions greater than 14 do not install correctly. Please monitor [Issue #2199] for an update to this limitation. We have found that Postgres 15 does install correctly in other environments (such as in <code>docker compose</code> setups).</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_2","title":"Categorized List of Pull Requests","text":"<ul> <li>Fixes for the <code>upgrade</code> Command</li> <li>Change upgrade definition file entry from 0.8.0 to 0.8.1 #2203 swcurran</li> <li>Add Upgrading ACA-Py document #2200 swcurran</li> <li>Fix: Indy WalletAlreadyOpenedError during upgrade process #2196 shaangill025</li> <li>Fix: Resolve Upgrade Config file in Container #2193 shaangill025</li> <li>Update and automate ACA-Py upgrade process #2185 shaangill025</li> <li>Adds the upgrade command YML file to the PyPi Release #2179 swcurran</li> <li>Test and Documentation</li> <li>3.7 and 3.10 unittests fix #2187 Jsyro</li> <li>Doc update and some test scripts #2189 ianco</li> <li>Create UnitTests.md #2183 swcurran</li> <li>Add link to recorded session about the ACA-Py Integration tests #2184 swcurran</li> <li>Release management pull requests</li> <li>0.8.1 #2207 swcurran</li> <li>0.8.1-rc2 #2198 swcurran</li> <li>0.8.1-rc1 #2194 swcurran</li> <li>0.8.1-rc0 #2190 swcurran</li> </ul>"},{"location":"CHANGELOG/#080","title":"0.8.0","text":""},{"location":"CHANGELOG/#march-14-2023","title":"March 14, 2023","text":"<p>0.8.0 is a breaking change that contains all updates since release 0.7.5. It extends the previously tagged <code>1.0.0-rc1</code> release because it is not clear when the 1.0.0 release will be finalized. Many of the PRs in this release were previously included in the <code>1.0.0-rc1</code> release. The categorized list of PRs separates those that are new from those in the <code>1.0.0-rc1</code> release candidate.</p> <p>There are not a lot of new Aries Framework features in this release, as the focus has been on cleanup and optimization. The biggest addition is the inclusion with ACA-Py of a universal resolver interface, allowing an instance to have both local resolvers for some DID Methods and a call out to an external universal resolver for other DID Methods. Another significant new capability is full support for Hyperledger Indy transaction endorsement for Authors and Endorsers. A new repo aries-endorser-service has been created that is a pre-configured instance of ACA-Py for use as an Endorser service.</p> <p>A recently completed feature that is outside of ACA-Py is a script to migrate existing ACA-Py storage from Indy SDK format to Aries Askar format. This enables existing deployments to switch to using the newer Aries Askar components. For details see the converter in the aries-acapy-tools repository.</p>"},{"location":"CHANGELOG/#container-publishing-updated","title":"Container Publishing Updated","text":"<p>With this release, a new automated process publishes container images in the Hyperledger container image repository. New images for the release are automatically published by the GitHubAction Workflows: publish.yml and publish-indy.yml. The actions are triggered when a release is tagged, so no manual action is needed. The images are published in the Hyperledger Package Repository under aries-cloudagent-python and a link to the packages added to the repositories main page (under \"Packages\"). Additional information about the container image publication process can be found in the document Container Images and Github Actions.</p> <p>The ACA-Py container images are based on Python 3.6 and 3.9 <code>slim-bullseye</code> images, and are designed to support <code>linux/386 (x86)</code>, <code>linux/amd64 (x64)</code>, and <code>linux/arm64</code>. However, for this release, the publication of multi-architecture containers is disabled. We are working to enable that through the updating of some dependencies that lack that capability. There are two flavors of image built for each Python version. One contains only the Indy/Aries Shared Libraries only (Aries Askar, Indy VDR and Indy Shared RS, supporting only the use of <code>--wallet-type askar</code>). The other (labelled <code>indy</code>) contains the Indy/Aries shared libraries and the Indy SDK (considered deprecated). For new deployments, we recommend using the Python 3.9 Shared Library images. For existing deployments, we recommend migrating to those images.</p> <p>Those currently using the container images published by BC Gov on Docker Hub should change to use those published to the Hyperledger Package Repository under aries-cloudagent-python.</p>"},{"location":"CHANGELOG/#breaking-changes-and-upgrades","title":"Breaking Changes and Upgrades","text":""},{"location":"CHANGELOG/#pr-2034-implicit-connections","title":"PR #2034 -- Implicit connections","text":"<p>The break impacts existing deployments that support implicit connections, those initiated by another agent using a Public DID for this instance instead of an explicit invitation. Such deployments need to add the configuration parameter <code>--requests-through-public-did</code> to continue to support that feature. The use case is that an ACA-Py instance publishes a public DID on a ledger with a DIDComm <code>service</code> in the DIDDoc. Other agents resolve that DID, and attempt to establish a connection with the ACA-Py instance using the <code>service</code> endpoint. This is called an \"implicit\" connection in RFC 0023 DID Exchange.</p>"},{"location":"CHANGELOG/#pr-1913-unrevealed-attributes-in-presentations","title":"PR #1913 -- Unrevealed attributes in presentations","text":"<p>Updates the handling of \"unrevealed attributes\" during verification of AnonCreds presentations, allowing them to be used in a presentation, with additional data that can be checked if for unrevealed attributes. As few implementations of Aries wallets support unrevealed attributes in an AnonCreds presentation, this is unlikely to impact any deployments.</p>"},{"location":"CHANGELOG/#pr-2145-update-webhook-message-to-terse-form-by-default-added-startup-flag-debug-webhooks-for-full-form","title":"PR #2145 - Update webhook message to terse form by default, added startup flag --debug-webhooks for full form","text":"<p>The default behavior in ACA-Py has been to keep the full text of all messages in the protocol state object, and include the full protocol state object in the webhooks sent to the controller. When the messages include an object that is very large in all the messages, the webhook may become too big to be passed via HTTP. For example, issuing a credential with a photo as one of the claims may result in a number of copies of the photo in the protocol state object and hence, very large webhooks. This change reduces the size of the webhook message by eliminating redundant data in the protocol state of the \"Issue Credential\" message as the default, and adds a new parameter to use the old behavior.</p>"},{"location":"CHANGELOG/#upgrade-pr-2116-upgrade-fix-multi-use-invitation-performance","title":"UPGRADE PR #2116 - UPGRADE: Fix multi-use invitation performance","text":"<p>The way that multiuse invitations in previous versions of ACA-Py caused performance to degrade over time. An update was made to add state into the tag names that eliminated the need to scan the tags when querying storage for the invitation.</p> <p>If you are using multiuse invitations in your existing (pre-<code>0.8.0</code> deployment of ACA-Py, you can run an <code>upgrade</code> to apply this change. To run upgrade from previous versions, use the following command using the <code>0.8.0</code> version of ACA-Py, adding you wallet settings:</p> <p><code>aca-py upgrade &lt;other wallet config settings&gt; --from-version=v0.7.5 --upgrade-config-path ./upgrade.yml</code></p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_3","title":"Categorized List of Pull Requests","text":"<ul> <li>Verifiable credential, presentation and revocation handling updates</li> <li>BREAKING: Update webhook message to terse form [default, added startup flag --debug-webhooks for full form #2145 by victorlee0505</li> <li>Add startup flag --light-weight-webhook to trim down outbound webhook payload #1941 victorlee0505</li> <li>feat: add verification method issue-credentials-2.0/send endpoint #2135 chumbert</li> <li>Respect auto-verify-presentation flag in present proof v1 and v2 #2097 dbluhm</li> <li>Feature: enabled handling VPs (request, creation, verification) with different VCs #1956 (teanas)</li> <li>fix: update issue-credential endpoint summaries #1997 (PeterStrob)</li> <li>fix claim format designation in presentation submission #2013 (rmnre)</li> <li>#2041 - Issue JSON-LD has invalid Admin API documentation #2046 (jfblier-amplitude)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Refactor ledger correction code and insert into revocation error handling #1892 (ianco)</li> <li>Indy ledger fixes and cleanups #1870 (andrewwhitehead)</li> <li>Refactoring of revocation registry creation #1813 (andrewwhitehead)</li> <li>Fix: \bthe type of tails file path to string. #1925 (baegjae)</li> <li>Pre-populate revoc_reg_id on IssuerRevRegRecord #1924 (andrewwhitehead)</li> <li>Leave credentialStatus element in the LD credential #1921 (tsabolov)</li> <li>BREAKING: Remove aca-py check for unrevealed revealed attrs on proof validation #1913 (ianco)</li> <li>Send webhooks upon record/credential deletion #1906 (frostyfrog)</li> </ul> </li> <li> <p>Out of Band (OOB) and DID Exchange / Connection Handling / Mediator</p> </li> <li>UPGRADE: Fix multi-use invitation performance #2116 reflectivedevelopment</li> <li>fix: public did mediator routing keys as did keys #1977 (dbluhm)</li> <li>Fix for mediator load testing race condition when scaling horizontally #2009 (ianco)</li> <li>BREAKING: Allow multi-use public invites and public invites with metadata #2034 (mepeltier)</li> <li>Do not reject OOB invitation with unknown handshake protocol\\(s\\) #2060 (andrewwhitehead)</li> <li>fix: fix connection timing bug #2099 (reflectivedevelopment)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fix: <code>--mediator-invitation</code> with OOB invitation + cleanup  #1970 (shaangill025)</li> <li>include image_url in oob invitation #1966 (Zzocker)</li> <li>feat: 00B v1.1 support #1962 (shaangill025)</li> <li>Fix: OOB - Handling of minor versions #1940 (shaangill025)</li> <li>fix: failed connectionless proof request on some case #1933 (kukgini)</li> <li>fix: propagate endpoint from mediation record #1922 (cjhowland)</li> <li>Feat/public did endpoints for agents behind mediators #1899 (cjhowland)</li> </ul> </li> <li> <p>DID Registration and Resolution related updates</p> </li> <li>feat: allow marking non-SOV DIDs as public #2144 chumbert</li> <li>fix: askar exception message always displaying null DID #2155 chumbert</li> <li>feat: enable creation of DIDs for all registered methods #2067 (chumbert)</li> <li>fix: create local DID return schema #2086 (chumbert)</li> <li>feat: universal resolver - configurable authentication #2095 (chumbert)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>feat: add universal resolver #1866 (dbluhm)</li> <li>fix: resolve dids following new endpoint rules #1863 (dbluhm)</li> <li>fix: didx request cannot be accepted #1881 (rmnre)</li> <li>did method &amp; key type registry #1986 (burdettadam)</li> <li>Fix/endpoint attrib structure #1934 (cjhowland)</li> <li>Simple did registry #1920 (burdettadam)</li> <li>Use did:key for recipient keys #1886 (frostyfrog)</li> </ul> </li> <li> <p>Hyperledger Indy Endorser/Author Transaction Handling</p> </li> <li>Update some of the demo Readme and Endorser instructions #2122 swcurran</li> <li>Special handling for the write ledger #2030 (ianco)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fix/txn job setting #1994 (ianco)</li> <li>chore: fix ACAPY_PROMOTE-AUTHOR-DID flag  #1978 (morrieinmaas)</li> <li>Endorser write DID transaction #1938 (ianco)</li> <li>Endorser doc updates and some bug fixes #1926 (ianco)</li> </ul> </li> <li> <p>Admin API Additions</p> </li> <li>fix: response type on delete-tails-files endpoint #2133 chumbert</li> <li>OpenAPI validation fixes #2127 loneil</li> <li> <p>Delete tail files #2103 ramreddychalla94</p> </li> <li> <p>Startup Command Line / Environment / YAML Parameter Updates</p> </li> <li>Update webhook message to terse form [default, added startup flag --debug-webhooks for full form #2145 by victorlee0505</li> <li>Add startup flag --light-weight-webhook to trim down outbound webhook payload #1941 victorlee0505</li> <li>Add missing --mediator-connections-invite cmd arg info to docs #2051 (matrixik)</li> <li>Issue #2068 boolean flag change to support HEAD requests to default route #2077 (johnekent)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Add seed command line parameter but use only if also an \"allow insecure seed\" parameter is set #1714 (DaevMithran)</li> </ul> </li> <li> <p>Internal Aries framework data handling updates</p> </li> <li>fix: resolver api schema inconsistency #2112 (TimoGlastra)</li> <li>fix: return if return route but no response #1853 (TimoGlastra)</li> <li>Multi-ledger/Multi-tenant issues #2022 (ianco)</li> <li>fix: Correct typo in model -- required spelled incorrectly #2031 (swcurran)</li> <li>Code formatting #2053 (ianco)</li> <li>Improved validation of record state attributes #2071 (rmnre)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>fix: update RouteManager methods use to pass profile as parameter #1902 (chumbert)</li> <li>Allow fully qualified class names for profile managers #1880 (chumbert)</li> <li>fix: unable to use askar with in memory db #1878 (dbluhm)</li> <li>Enable manually triggering keylist updates during connection #1851 (dbluhm)</li> <li>feat: make base wallet route access configurable #1836 (dbluhm)</li> <li>feat: event and webhook on keylist update stored #1769 (dbluhm)</li> <li>fix: Safely shutdown when root_profile uninitialized #1960 (frostyfrog)</li> <li>feat: include connection ids in keylist update webhook #1914 (dbluhm)</li> <li>fix: incorrect response schema for discover features #1912 (dbluhm)</li> <li>Fix: SchemasInputDescriptorFilter: broken deserialization renders generated clients unusable #1894 (rmnre)</li> <li>fix: schema class can set Meta.unknown #1885 (dbluhm)</li> </ul> </li> <li> <p>Unit, Integration, and Aries Agent Test Harness Test updates </p> </li> <li>Additional integration tests for revocation scenarios #2055 (ianco)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fixes a few AATH failures #1897 (ianco)</li> <li>fix: warnings in tests from IndySdkProfile #1865 (dbluhm)</li> <li>Unit test fixes for python 3.9 #1858 (andrewwhitehead)</li> <li>Update pip-audit.yml #1945 (ryjones)</li> <li>Update pip-audit.yml #1944 (ryjones)</li> </ul> </li> <li> <p>Dependency, Python version, GitHub Actions and Container Image Changes</p> </li> <li>Remove CircleCI Status since we aren't using CircleCI anymore #2163 swcurran</li> <li>Update ACA-Py docker files to produce OpenShift compatible images #2130 WadeBarnes</li> <li>Temporarily disable multi-architecture image builds #2125 WadeBarnes</li> <li>Fix ACA-py image builds #2123 WadeBarnes</li> <li>Fix publish workflows #2117 WadeBarnes</li> <li>fix: indy dependency version format #2054 (chumbert)</li> <li>ci: add gha for pr-tests #2058 (dbluhm)</li> <li>ci: test additional versions of python nightly #2059 (dbluhm)</li> <li>Update github actions dependencies \\(for node16 support\\) #2066 (andrewwhitehead)</li> <li>Docker images and GHA for publishing images #2076 (dbluhm)</li> <li>Update dockerfiles to use python 3.9 #2109 (ianco)</li> <li>Updating base images from slim-buster to slim-bullseye #2105 (pradeepp88)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>feat: update pynacl version from 1.4.0 to 1.50 #1981 (morrieinmaas)</li> <li>Fix: web.py dependency - integration tests &amp; demos #1973 (shaangill025)</li> <li>chore: update pydid #1915 (dbluhm)</li> </ul> </li> <li> <p>Demo and Documentation Updates</p> </li> <li>[fix] Removes extra comma that prevents swagger from accepting the presentation request #2149 swcurran</li> <li>Initial plugin docs #2138 ianco</li> <li>Acme workshop #2137 ianco</li> <li>Fix: Performance Demo [no --revocation] #2151 shaangill025</li> <li>Fix typos in alice-local.sh &amp; faber-local.sh #2010 (naonishijima)</li> <li>Added a bit about manually creating a revoc reg tails file #2012 (ianco)</li> <li>Add ability to set docker container name #2024 (matrixik)</li> <li>Doc updates for json demo #2026 (ianco)</li> <li>Multitenancy demo \\(docker-compose with postgres and ngrok\\) #2089 (ianco)</li> <li>Allow using YAML configuration file with run_docker #2091 (matrixik)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fixes to acme exercise code #1990 (ianco)</li> <li>Fixed bug in run_demo script #1982 (pasquale95)</li> <li>Transaction Author with Endorser demo #1975 (ianco)</li> <li>Redis Plugins [redis_cache &amp; redis_queue] related updates #1937 (shaangill025)</li> </ul> </li> <li> <p>Release management pull requests</p> </li> <li>0.8.0 release #2169 (swcurran)</li> <li>0.8.0-rc0 release updates #2115 (swcurran)</li> <li>Previously flagged in release 1.0.0-rc1<ul> <li>Release 1.0.0-rc0 #1904 (swcurran)</li> <li>Add 0.7.5 patch Changelog entry to main branch Changelog #1996 (swcurran)</li> <li>Release 1.0.0-rc1 #2005 (swcurran)</li> </ul> </li> </ul>"},{"location":"CHANGELOG/#075","title":"0.7.5","text":""},{"location":"CHANGELOG/#october-26-2022","title":"October 26, 2022","text":"<p>0.7.5 is a patch release to deal primarily to add PR #1881 DID Exchange in ACA-Py 0.7.4 with explicit invitations and without auto-accept broken. A couple of other PRs were added to the release, as listed below, and in Milestone 0.7.5.</p>"},{"location":"CHANGELOG/#list-of-pull-requests","title":"List of Pull Requests","text":"<ul> <li>Changelog and version updates for version 0.7.5-rc1 #1985 (swcurran)</li> <li>Endorser doc updates and some bug fixes #1926 (ianco)</li> <li>Fix: web.py dependency - integration tests &amp; demos #1973 (shaangill025)</li> <li>Endorser write DID transaction #1938 (ianco)</li> <li>fix: didx request cannot be accepted #1881 (rmnre)</li> <li>Fix: OOB - Handling of minor versions #1940 (shaangill025)</li> <li>fix: Safely shutdown when root_profile uninitialized #1960 (frostyfrog)</li> <li>feat: 00B v1.1 support #1962 (shaangill025)</li> <li>0.7.5 Cherry Picks #1967 (frostyfrog)</li> <li>Changelog and version updates for version 0.7.5-rc0 #1969 (swcurran)</li> <li>Final 0.7.5 changes #1991 (swcurran)</li> </ul>"},{"location":"CHANGELOG/#074","title":"0.7.4","text":""},{"location":"CHANGELOG/#june-30-2022","title":"June 30, 2022","text":"<p> Existing multitenant JWTs invalidated when a new JWT is generated: If you have a pre-existing implementation with existing Admin API authorization JWTs, invoking the endpoint to get a JWT now invalidates the existing JWT. Previously an identical JWT would be created. Please see this comment on PR #1725 for more details.</p> <p>0.7.4 is a significant release focused on stability and production deployments. As the \"patch\" release number indicates, there were no breaking changes in the Admin API, but a huge volume of updates and improvements.  Highlights of this release include:</p> <ul> <li>A major performance and stability improvement resulting from the now recommended use of Aries Askar instead of the Indy-SDK.</li> <li>There are significant improvements and tools for dealing with revocation-related issues.</li> <li>A lot of work has been on the handling of Hyperledger Indy transaction endorsements.</li> <li>ACA-Py now has a pluggable persistent queues mechanism in place, with Redis and Kafka support available (albeit with work still to come on documentation).</li> </ul> <p>In addition, there are a significant number of general enhancements, bug fixes, documentation updates and code management improvements.</p> <p>This release is a reflection of the many groups stressing ACA-Py in production environments, reporting issues and the resulting solutions. We also have a very large number of contributors to ACA-Py, with this release having PRs from 22 different individuals. A big thank you to all of those using ACA-Py, raising issues and providing solutions.</p>"},{"location":"CHANGELOG/#major-enhancements","title":"Major Enhancements","text":"<p>A lot of work has been put into this release related to performance and load testing, with significant updates being made to the key \"shared component\" ACA-Py dependencies (Aries Askar, Indy VDR) and Indy Shared RS (including CredX). We now recommend using those components (by using <code>--wallet-type askar</code> in the ACA-Py startup parameters) for new ACA-Py deployments. A wallet migration tool from indy-sdk storage to Askar storage is still needed before migrating existing deployment to Askar. A big thanks to those creating/reporting on stress test scenarios, and especially the team at LISSI for creating the aries-cloudagent-loadgenerator to make load testing so easy! And of course to the core ACA-Py team for addressing the findings.</p> <p>The largest enhancement is in the area of the endorsing of Hyperledger Indy ledger transactions, enabling an instance of ACA-Py to act as an Endorser for Indy authors needing endorsements to write objects to an Indy ledger. We're working on an Aries Endorser Service based on the new capabilities in ACA-Py, an Endorser to be easily operated by an organization, ideally with a controller starter kit supporting a basic human and automated approvals business workflow. Contributions welcome!</p> <p>A focus towards the end of the 0.7.4 development and release cycle was on the handling of AnonCreds revocation in ACA-Py. Most important, a production issue was uncovered where by an ACA-Py issuer's local Revocation Registry data could get out of sync with what was published on an Indy ledger, resulting in an inability to publish new RevRegEntry transactions -- making new revocations impossible. As a result, we have added some new endpoints to enable an update to the RevReg storage such that RevRegEntry transactions can again be published to the ledger. Other changes were added related to revocation in general and in the handling of tails files in particular.</p> <p>The team has worked a lot on evolving the persistent queue (PQ) approach available in ACA-Py. We have landed on a design for the queues for inbound and outbound messages using a default in-memory implementation, and the ability to replace the default method with implementations created via an ACA-Py plugin. There are two concrete, out-of-the-box external persistent queuing solutions available for Redis and Kafka. Those ACA-Py persistent queue implementation repositories will soon be migrated to the Aries project within the Hyperledger Foundation's GitHub organization. Anyone else can implement their own queuing plugin as long as it uses the same interface.</p> <p>Several new ways to control ACA-Py configurations were added, including new startup parameters, Admin API parameters to control instances of protocols, and additional web hook notifications.</p> <p>A number of fixes were made to the Credential Exchange protocols, both for V1 and V2, and for both AnonCreds and W3C format VCs. Nothing new was added and there no changes in the APIs.</p> <p>As well there were a number of internal fixes, dependency updates, documentation and demo changes, developer tools and release management updates. All the usual stuff needed for a healthy, growing codebase.</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_4","title":"Categorized List of Pull Requests","text":"<ul> <li>Hyperledger Indy Endorser related updates:</li> <li>Fix order of operations connecting faber to endorser #1716 (ianco)</li> <li>Endorser support for updating DID endpoints on ledger #1696 (frostyfrog)</li> <li>Add \"sent\" key to both Schema and Cred Defs when using Endorsers #1663 (frostyfrog)</li> <li>Add cred_def_id to metadata when using an Endorser #1655 (frostyfrog)</li> <li>Update Endorser documentation #1646 (chumbert)</li> <li>Auto-promote author did to public after endorsing #1607 (ianco)</li> <li>DID updates for endorser #1601 (ianco)</li> <li>Qualify did exch connection lookup by role #1670 (ianco)</li> <li> <p>Use provided connection_id if provided #1726 (ianco)</p> </li> <li> <p>Additions to the startup parameters, Admin API and Web Hooks</p> </li> <li>Improve typing of settings and add plugin settings object #1833 (dbluhm)</li> <li>feat: accept taa using startup parameter --accept-taa #1643 (TimoGlastra)</li> <li>Add auto_verify flag in present-proof protocol #1702 (DaevMithran)</li> <li>feat: query connections by their_public_did #1637 (TimoGlastra)</li> <li>feat: enable webhook events for mediation records #1614 (TimoGlastra)</li> <li>Feature/undelivered events #1694 (mepeltier)</li> <li>Allow use of SEED when creating local wallet DID Issue-1682 Issue-1682 #1705 (DaevMithran)</li> <li>Feature: Add the ability to deny specific plugins from loading #1737 (frostyfrog)</li> <li>feat: Add filter param to connection list for invitations #1797 (frostyfrog)</li> <li> <p>Fix missing webhook handler #1816 (ianco)</p> </li> <li> <p>Persistent Queues</p> </li> <li> <p>Redis PQ Cleanup in preparation for enabling the uses of plugin PQ implementations [Issue#1659] #1659 (shaangill025)</p> </li> <li> <p>Credential Revocation and Tails File Handling</p> </li> <li>Fix handling of non-revocable credential when timestamp is specified \\(askar/credx\\) #1847 (andrewwhitehead)</li> <li>Additional endpoints to get revocation details and fix \"published\" status #1783 (ianco)</li> <li>Fix IssuerCredRevRecord state update on revocation publish #1827 (andrewwhitehead)</li> <li>Fix put_file when the server returns a redirect #1808 (andrewwhitehead)</li> <li>Adjust revocation registry update procedure to shorten transactions #1804 (andrewwhitehead)</li> <li>fix: Resolve Revocation Notification environment variable name collision #1751 (frostyfrog)</li> <li>fix: always notify if revocation notification record exists #1665 (TimoGlastra)</li> <li>Fix for AnonCreds non-revoc proof with no timestamp #1628 (ianco)</li> <li>Fixes for v7.3.0 - Issue #1597 #1711 (shaangill025)<ul> <li>Fixes Issue 1 from #1597: Tails file upload fails when a credDef is created and multi ledger support is enabled</li> </ul> </li> <li>Fix tails server upload multi-ledger mode #1785 (ianco)</li> <li> <p>Feat/revocation notification v2 #1734 (frostyfrog)</p> </li> <li> <p>Issue Credential, Present Proof updates/fixes</p> </li> <li>Fix: Present Proof v2 - check_proof_vs_proposal update to support proof request with restrictions #1820 (shaangill025)</li> <li>Fix: present-proof v1 send-proposal flow #1811 (shaangill025)</li> <li>Prover - verification outcome from presentation ack message #1757 (shaangill025)</li> <li>feat: support connectionless exchange #1710 (TimoGlastra)</li> <li>Fix: DIF proof proposal when creating bound presentation request [Issue#1687] #1690 (shaangill025)</li> <li>Fix DIF PresExch and OOB request_attach delete unused connection #1676 (shaangill025)</li> <li>Fix DIFPresFormatHandler returning invalid V20PresExRecord on presentation verification #1645 (rmnre)</li> <li>Update aries-askar patch version to at least 0.2.4 as 0.2.3 does not include backward compatibility #1603 (acuderman)</li> <li>Fixes for credential details in issue-credential webhook responses #1668 (andrewwhitehead)</li> <li>Fix: present-proof v2 send-proposal issue#1474 #1667 (shaangill025)<ul> <li>Fixes Issue 3b from #1597: V2 Credential exchange ignores the auto-respond-credential-request</li> </ul> </li> <li>Revert change to send_credential_ack return value #1660 (andrewwhitehead)</li> <li>Fix usage of send_credential_ack #1653 (andrewwhitehead)</li> <li>Replace blank credential/presentation exchange states with abandoned state #1605 (andrewwhitehead)<ul> <li>Fixes Issue 4 from #1597: Wallet type askar has issues when receiving V1 credentials</li> </ul> </li> <li>Fixes and cleanups for issue-credential 1.0 #1619 (andrewwhitehead)</li> <li> <p>Fix: Duplicated schema and cred_def - Askar and Postgres #1800 (shaangill025)</p> </li> <li> <p>Mediator updates and fixes</p> </li> <li>feat: allow querying default mediator from base wallet #1729 (dbluhm)</li> <li> <p>Added async with for mediator record delete #1749 (dejsenlitro)</p> </li> <li> <p>Multitenacy updates and fixes</p> </li> <li>feat: create new JWT tokens and invalidate older for multitenancy #1725 (TimoGlastra)</li> <li> <p>Multi-tenancy stale wallet clean up #1692 (dbluhm)</p> </li> <li> <p>Dependencies and internal code updates/fixes</p> </li> <li>Update pyjwt to 2.4 #1829 (andrewwhitehead)</li> <li>Fix external Outbound Transport loading code #1812 (frostyfrog)</li> <li>Fix iteration over key list, update Askar to 0.2.5 #1740 (andrewwhitehead)</li> <li>Fix: update IndyLedgerRequestsExecutor logic - multitenancy and basic base wallet type  #1700 (shaangill025)</li> <li>Move database operations inside the session context #1633 (acuderman)</li> <li>Upgrade ConfigArgParse to version 1.5.3 #1627 (WadeBarnes)</li> <li>Update aiohttp dependency #1606 (acuderman)</li> <li>did-exchange implicit request pthid update &amp; invitation key verification #1599 (shaangill025)</li> <li>Fix auto connection response not being properly mediated #1638 (dbluhm)</li> <li>platform target in run tests. #1697 (burdettadam)</li> <li>Add an integration test for mixed proof with a revocable cred and a n\u2026 #1672 (ianco)</li> <li>Fix: Inbound Transport is_external attribute #1802 (shaangill025)</li> <li>fix: add a close statement to ensure session is closed on error #1777 (reflectivedevelopment)</li> <li>Adds <code>transport_id</code> variable assignment back to outbound enqueue method #1776 (amanji)</li> <li> <p>Replace async workaround within document loader #1774 (frostyfrog)</p> </li> <li> <p>Documentation and Demo Updates</p> </li> <li>Use default wallet type askar for alice/faber demo and bdd tests #1761 (ianco)</li> <li>Update the Supported RFCs document for 0.7.4 release #1846 (swcurran)</li> <li>Fix a typo in DevReadMe.md #1844 (feknall)</li> <li>Add troubleshooting document, include initial examples - ledger connection, out-of-sync RevReg #1818 (swcurran)</li> <li>Update POST /present-proof/send-request to POST /present-proof-2.0/send-request #1824 (lineko)</li> <li>Fetch from --genesis-url likely to fail in composed container #1746 (tdiesler)</li> <li>Fixes logic for web hook formatter in Faber demo #1739 (amanji)</li> <li>Multitenancy Docs Update #1706 (MonolithicMonk)</li> <li>#1674 Add basic DOCKER_ENV logging for run_demo #1675 (tdiesler)</li> <li>Performance demo updates #1647 (ianco)</li> <li>docs: supported features attribution #1654 (TimoGlastra)</li> <li>Documentation on existing language wrappers for aca-py #1738 (etschelp)</li> <li> <p>Document impact of multi-ledger on TAA acceptance #1778 (ianco)</p> </li> <li> <p>Code management and contributor/developer support updates</p> </li> <li>Set prefix for integration test demo agents; some code cleanup #1840 (andrewwhitehead)</li> <li>Pin markupsafe at version 2.0.1 #1642 (andrewwhitehead)</li> <li>style: format with stable black release #1615 (TimoGlastra)</li> <li>Remove references to play with von #1688 (ianco)</li> <li>Add pre-commit as optional developer tool #1671 (dbluhm)</li> <li>run_docker start - pass environment variables #1715 (shaangill025)</li> <li>Use local deps only #1834 (ryjones)</li> <li>Enable pip-audit #1831 (ryjones)</li> <li> <p>Only run pip-audit on main repo #1845 (ryjones)</p> </li> <li> <p>Release management pull requests</p> </li> <li>0.7.4 Release Changelog and version update #1849 (swcurran)</li> <li>0.7.4-rc5 changelog, version and ReadTheDocs updates #1838 (swcurran)</li> <li>Update changelog and version for 0.7.4-rc4 #1830 (swcurran)</li> <li>Changelog, version and ReadTheDocs updates for 0.7.4-rc3 release #1817 (swcurran)</li> <li>0.7.4-rc2 update #1771 (swcurran)</li> <li>Some ReadTheDocs File updates #1770 (swcurran)</li> <li>0.7.4-RC1 Changelog intro paragraph - fix copy/paste error #1753 (swcurran)</li> <li>Fixing the intro paragraph and heading in the changelog of this 0.7.4RC1 #1752 (swcurran)</li> <li>Updates to Changelog for 0.7.4. RC1 release #1747 (swcurran)</li> <li>Prep for adding the 0.7.4-rc0 tag #1722 (swcurran)</li> <li>Added missed new module -- upgrade -- to the RTD generated docs #1593 (swcurran)</li> <li>Doh....update the date in the Changelog for 0.7.3 #1592 (swcurran)</li> </ul>"},{"location":"CHANGELOG/#073","title":"0.7.3","text":""},{"location":"CHANGELOG/#january-10-2022","title":"January 10, 2022","text":"<p>This release includes some new AIP 2.0 features out (Revocation Notification and Discover Features 2.0), a major new feature for those using Indy ledger (multi-ledger support), a new \"version upgrade\" process that automates updating data in secure storage required after a new release, and a fix for a critical bug in some mediator scenarios. The release also includes several new pieces of documentation (upgrade processing, storage database information and logging) and some other documentation updates that make the ACA-Py Read The Docs site useful again. And of course, some recent bug fixes and cleanups are included.</p> <p>There is a BREAKING CHANGE for those deploying ACA-Py with an external outbound queue implementation (see PR #1501). As far as we know, there is only one organization that has such an implementation and they were involved in the creation of this PR, so we are not making this release a minor or major update. However, anyone else using an external queue should be aware of the impact of this PR that is included in the release.</p> <p>For those that have an existing deployment of ACA-Py with long-lasting connection records, an upgrade is needed to use RFC 434 Out of Band and the \"reuse connection\" as the invitee. In PR #1453 (details below) a performance improvement was made when finding a connection for reuse. The new approach (adding a tag to the connection to enable searching) applies only to connections made using this ACA-Py release and later, and \"as-is\" connections made using earlier releases of ACA-Py will not be found as reuse candidates. A new \"Upgrade deployment\" capability (#1557, described below) must be executed to update your deployment to add tags for all existing connections.</p> <p>The Supported RFCs document has been updated to reflect the addition of the AIP 2.0 RFCs for which support was added.</p> <p>The following is an annotated list of PRs in the release, including a link to each PR.</p> <ul> <li>AIP 2.0 Features</li> <li>Discover Features Protocol: v1_0 refactoring and v2_0 implementation #1500<ul> <li>Updates the Discover Features 1.0 (AIP 1.0) implementation and implements the new 2.0 version. In doing so, adds generalized support for goal codes to ACA-Py.</li> <li>fix DiscoveryExchangeRecord RECORD_TOPIC typo fix #1566</li> </ul> </li> <li>Implement Revocation Notification v1.0 #1464</li> <li>Fix integration tests (revocation notifications) #1528</li> <li>Add Revocation notification support to alice/faber #1527</li> <li>Other New Features</li> <li>Multiple Indy Ledger support and State Proof verification #1425<ul> <li>Remove required dependencies from multi-ledger code that was requiring the import of Aries Askar even when not being used#1550</li> <li>Fixed IndyDID resolver bug after Tag 0.7.3rc0 created #1569</li> <li>Typo vdr service name #1563</li> <li>Fixes and cleanup for multiple ledger support with Askar #1583</li> </ul> </li> <li>Outbound Queue - more usability improvements #1501</li> <li>Display QR code when generating/displaying invites on startup #1526</li> <li>Enable WS Pings for WS Inbound Transport #1530<ul> <li>Faster detection of lost Web Socket connections; implementation verified with an existing mediator.</li> </ul> </li> <li>Performance Improvement when using connection reuse in OOB and there are many DID connections. ConnRecord tags - their_public_did and invitation_msg_id #1543<ul> <li>In previous releases, a \"their_public_did\" was not a tag, so to see if you can reuse a connection, all connections were retrieved from the database to see if a matching public DID can be found. Now, connections created after deploying this release will have a tag on the connection such that an indexed query can be used. See \"Breaking Change\" note above and \"Update\" feature below.</li> <li>Follow up to #1543 - Adding invitation_msg_id and their_public_did back to record_value #1553</li> </ul> </li> <li>A generic \"Upgrade Deployment\" capability was added to ACA-Py that operates like a database migration capability in relational databases. When executed (via a command line option), a current version of the deployment is detected and if any storage updates need be applied to be consistent with the new version, they are, and the stored \"current version\"is updated to the new version. An instance of this capability can be used to address the new feature #1543 documented above. #1557</li> <li>Adds a \"credential_revoked\" state to the Issue Credential protocol state object. When the protocol state object is retained past the completion of the protocol, it is updated when the credential is revoked. #1545</li> <li>Updated a missing dependency that recently caused an error when using the <code>--version</code> command line option #1589</li> <li>Critical Fixes</li> <li>Fix connection record response for mobile #1469</li> <li>Documentation Additions and Updates</li> <li>added documentation for wallet storage databases #1523</li> <li>added logging documentation #1519</li> <li>Fix warnings when generating ReadTheDocs #1509</li> <li>Remove Streetcred references #1504</li> <li>Add RTD configs to get generator working #1496</li> <li>The Alice/Faber demo was updated to allow connections based on Public DIDs to be established, including reusing a connection if there is an existing connection. #1574</li> <li>Other Fixes</li> <li>Connection Handling / Out of Band Invitations Fixes<ul> <li>OOB: Fixes issues with multiple public explicit invitation and unused 0160 connection #1525</li> <li>OOB added webhooks to notify the controller when a connection reuse message is used in response to an invitation #1581</li> <li>Delete unused ConnRecord generated - OOB invitation (use_exising_connection) #1521</li> <li>When an invitee responded with a \"reuse\" message, the connection record associated with the invitation was not being deleted. Now it is.</li> <li>Await asyncio.sleeps to cleanup warnings in Python 3.8/3.9 #1558</li> <li>Add alias field to didexchange invitation UI #1561</li> <li>fix: use invitation key for connection query #1570</li> <li>Fix the inconsistency of invitation_msg_id between invitation and response #1564</li> <li>chore: update pydid to ^0.3.3 #1562</li> </ul> </li> <li>DIF Presentation Exchange Cleanups<ul> <li>Fix DIF Presentation Request Input Validation #1517</li> <li>Some validation checking of a DIF presentation request to prevent uncaught errors later in the process.</li> <li>DIF PresExch - ProblemReport and \"is_holder\" #1493</li> <li>Cleanups related to when \"is_holder\" is or is not required. Related to Issue #1486</li> </ul> </li> <li>Indy SDK Related Fixes<ul> <li>Fix AttributeError when writing an Indy Cred Def record #1516</li> <li>Fix TypeError when calling credential_definitions_fix_cred_def_wallet\u2026 #1515</li> <li>Fix TypeError when writing a Schema record #1494</li> <li>Fix validation for range checks #1538</li> <li>Back out some of the validation checking for proof requests with predicates as they were preventing valid proof requests from being processed.</li> </ul> </li> <li>Aries Askar Related Fixes:<ul> <li>Fix bug when getting credentials on askar-profile #1510</li> <li>Fix error when removing a wallet on askar-profile #1518</li> <li>Fix error when connection request is received (askar, public invitation) #1508</li> <li>Fix error when an error occurs while issuing a revocable credential #1591</li> </ul> </li> <li>Docker fixes:<ul> <li>Update docker scripts to use new &amp; improved docker IP detection #1565</li> </ul> </li> <li>Release Adminstration:<ul> <li>Changelog and RTD updates for the pending 0.7.3 release #1553</li> </ul> </li> </ul>"},{"location":"CHANGELOG/#072","title":"0.7.2","text":""},{"location":"CHANGELOG/#november-15-2021","title":"November 15, 2021","text":"<p>A mostly maintenance release with some key updates and cleanups based on community deployments and discovery. With usage in the field increasing, we're cleaning up edge cases and issues related to volume deployments.</p> <p>The most significant new feature for users of Indy ledgers is a simplified approach for transaction authors getting their transactions signed by an endorser. Transaction author controllers now do almost nothing other than configuring their instance to use an Endorser, and ACA-Py takes care of the rest. Documentation of that feature is here.</p> <ul> <li>Improve cloud native deployments/scaling</li> <li>unprotect liveness and readiness endpoints #1416</li> <li>Open askar sessions only on demand - Connections #1424</li> <li>Fixed potential deadlocks by opening sessions only on demand (Wallet endpoints) #1472</li> <li>Fixed potential deadlocks by opening sessions only on demand #1439</li> <li>Make mediation invitation parameter idempotent #1413</li> <li>Indy Transaction Endorser Support Added</li> <li>Endorser protocol configuration, automation and demo integration #1422</li> <li>Auto connect from author to endorser on startup #1461</li> <li>Startup and shutdown events (prep for endorser updates) #1459</li> <li>Endorser protocol askar fixes #1450</li> <li>Endorser protocol updates - refactor to use event bus #1448</li> <li>Indy verifiable credential/presentation fixes and updates</li> <li>Update credential and proof mappings to allow negative encoded values #1475</li> <li>Add credential validation to offer issuance step #1446</li> <li>Fix error removing proof req entries by timestamp #1465</li> <li>Fix issue with cred limit on presentation endpoint #1437</li> <li>Add support for custom offers from the proposal #1426</li> <li>Make requested attributes and predicates required on indy proof request #1411</li> <li>Remove connection check on proof verify #1383</li> <li>General cleanups and improvements to existing features</li> <li>Fixes failing integration test -- JSON-LD context URL not loading because of external issue #1491</li> <li>Update base record time-stamp to standard ISO format #1453</li> <li>Encode DIDComm messages before sent to the queue #1408</li> <li>Add Event bus Metadata #1429</li> <li>Allow base wallet to connect to a mediator after startup #1463</li> <li>Log warning when unsupported problem report code is received #1409</li> <li>feature/inbound-transport-profile #1407</li> <li>Import cleanups #1393</li> <li>Add no-op handler for generic ack message (RFC 0015) #1390</li> <li>Align OutOfBandManager.receive_invitation with other connection managers #1382</li> <li>Bug fixes</li> <li>fix: fixes error in use of a default mediator in connections/out of band -- mediation ID was being saved as None instead of the retrieved default mediator value #1490</li> <li>fix: help text for open-mediation flag #1445</li> <li>fix: incorrect return type #1438</li> <li>Add missing param to ws protocol #1442</li> <li>fix: create static doc use empty endpoint if None #1483</li> <li>fix: use named tuple instead of dataclass in mediation invite store #1476</li> <li>When fetching the admin config, don't overwrite webhook settings #1420</li> <li>fix: return type of inject #1392</li> <li>fix: typo in connection static result schema #1389</li> <li>fix: don't require push on outbound queue implementations #1387</li> <li>Updates/Fixes to the Alice/Faber demo and integration tests</li> <li>Clarify instructions in the Acme Controller Demo #1484</li> <li>Fix aip 20 behaviour and other cleanup #1406</li> <li>Fix issue with startup sequence for faber agent #1415</li> <li>Connectionless proof demo #1395</li> <li>Typos in the demo's README.md #1405</li> <li>Run integration tests using external ledger and tails server #1400</li> <li>Chores</li> <li>Update CONTRIBUTING.md #1428</li> <li>Update to ReadMe and Supported RFCs for 0.7.2 #1489</li> <li>Updating the RTDs code for Release 0.7.2 - Try 2 #1488</li> </ul>"},{"location":"CHANGELOG/#071","title":"0.7.1","text":""},{"location":"CHANGELOG/#august-31-2021","title":"August 31, 2021","text":"<p>A relatively minor maintenance release to address issues found since the 0.7.0 Release. Includes some cleanups of JSON-LD Verifiable Credentials and Verifiable Presentations</p> <ul> <li>W3C  Verifiable Credential cleanups</li> <li>Timezone inclusion [ISO 8601] for W3C VC and Proofs (#1373)</li> <li>W3C VC handling where attachment is JSON and not Base64 encoded (#1352)</li> <li>Refactor outbound queue interface (#1348)</li> <li>Command line parameter handling for arbitrary plugins (#1347)</li> <li>Add an optional parameter '--ledger-socks-proxy' (#1342)</li> <li>OOB Protocol - CredentialOffer Support (#1316), (#1216)</li> <li>Updated IndyCredPrecisSchema - pres_referents renamed to presentation_referents (#1334)</li> <li>Handle unpadded protected header in PackWireFormat::get_recipient_keys (#1324)</li> <li>Initial cut of OpenAPI Code Generation guidelines (#1339)</li> <li>Correct revocation API in credential revocation documentation (#612)</li> <li>Documentation updates for Read-The-Docs (#1359, #1366, #1371)</li> <li>Add <code>inject_or</code> method to dynamic injection framework to resolve typing ambiguity (#1376)</li> <li>Other fixes:</li> <li>Indy Proof processing fix, error not raised in predicate timestamp check (#1364)</li> <li>Problem Report handler for connection specific problems (#1356)</li> <li>fix: error on deserializing conn record with protocol (#1325)</li> <li>fix: failure to verify jsonld on non-conformant doc but vaild vmethod (#1301)</li> <li>fix: allow underscore in endpoints (#1378)</li> </ul>"},{"location":"CHANGELOG/#070","title":"0.7.0","text":""},{"location":"CHANGELOG/#july-14-2021","title":"July 14, 2021","text":"<p>Another significant release, this version adds support for multiple new protocols, credential formats, and extension methods.</p> <ul> <li>Support for W3C Standard Verifiable Credentials based on JSON-LD using LD-Signatures and BBS+ Signatures, contributed by Animo Solutions - #1061</li> <li>Present Proof V2 including support for DIF Presentation Exchange - #1125</li> <li>Pluggable DID Resolver (with a did:web resolver) with fallback to an external DID universal resolver, contributed by Indicio - #1070</li> <li>Updates and extensions to ledger transaction endorsement via the Sign Attachment Protocol, contributed by AyanWorks - #1134, #1200</li> <li>Upgrades to Demos to add support for Credential Exchange 2.0 and W3C Verifiable Credentials #1235</li> <li>Alpha support for the Indy/Aries Shared Components (indy-vdr, indy-credx and aries-askar), which enable running ACA-Py without using Indy-SDK, while still supporting the use of Indy as a ledger, and Indy AnonCreds verifiable credentials #1267</li> <li>A new event bus for distributing internally generated ACA-Py events to controllers and other listeners, contributed by Indicio - #1063</li> <li>Enable operation without Indy ledger support if not needed</li> <li>Performance fix for deployments with large numbers of DIDs/connections #1249</li> <li>Simplify the creation/handling of plugin protocols #1086, #1133, #1226</li> <li>DID Exchange implicit invitation handling #1174</li> <li>Add support for Indy 1.16 predicates (restrictions on predicates based on attribute name and value) #1213</li> <li>BDD Tests run via GitHub Actions #1046</li> </ul>"},{"location":"CHANGELOG/#060","title":"0.6.0","text":""},{"location":"CHANGELOG/#february-25-2021","title":"February 25, 2021","text":"<p>This is a significant release of ACA-Py with several new features, as well as changes to the internal architecture in order to set the groundwork for using the new shared component libraries: indy-vdr, indy-credx, and aries-askar.</p>"},{"location":"CHANGELOG/#mediator-support","title":"Mediator support","text":"<p>While ACA-Py had previous support for a basic routing protocol, this was never fully developed or used in practice. Starting with this release, inbound and outbound connections can be established through a mediator agent using the Aries (Mediator Coordination Protocol)[https://github.com/hyperledger/aries-rfcs/tree/master/features/0211-route-coordination]. This work was initially contributed by Adam Burdett and Daniel Bluhm of Indicio on behalf of SICPA. Read more about mediation support.</p>"},{"location":"CHANGELOG/#multi-tenancy-support","title":"Multi-Tenancy support","text":"<p>Started by BMW and completed by Animo Solutions and Anon Solutions on behalf of SICPA, this feature allows for a single ACA-Py instance to host multiple wallet instances. This can greatly reduce the resources required when many identities are being handled. Read more about multi-tenancy support.</p>"},{"location":"CHANGELOG/#new-connection-protocols","title":"New connection protocol(s)","text":"<p>In addition to the Aries 0160 Connections RFC, ACA-Py now supports the Aries DID Exchange Protocol for connection establishment and reuse, as well as the Aries Out-of-Band Protocol for representing connection invitations and other pre-connection requests.</p>"},{"location":"CHANGELOG/#issue-credential-v2","title":"Issue-Credential v2","text":"<p>This release includes an initial implementation of the Aries Issue Credential v2 protocol.</p>"},{"location":"CHANGELOG/#notable-changes-for-administrators","title":"Notable changes for administrators","text":"<ul> <li> <p>There are several new endpoints available for controllers as well as new startup parameters related to the multi-tenancy and mediator features, see the feature description pages above in order to make use of these features. Additional admin endpoints are introduced for the DID Exchange, Issue Credential v2, and Out-of-Band protocols.</p> </li> <li> <p>When running <code>aca-py start</code>, a new wallet will no longer be created unless the <code>--auto-provision</code> argument is provided. It is recommended to always use <code>aca-py provision</code> to initialize the wallet rather than relying on automatic behaviour, as this removes the need for repeatedly providing the wallet seed value (if any). This is a breaking change from previous versions.</p> </li> <li> <p>When running <code>aca-py provision</code>, an existing wallet will not be removed and re-created unless the <code>--recreate-wallet</code> argument is provided. This is a breaking change from previous versions.</p> </li> <li> <p>The logic around revocation intervals has been tightened up in accordance with Present Proof Best Practices.</p> </li> </ul>"},{"location":"CHANGELOG/#notable-changes-for-plugin-writers","title":"Notable changes for plugin writers","text":"<p>The following are breaking changes to the internal APIs which may impact Python code extensions.</p> <ul> <li> <p>Manager classes generally accept a <code>Profile</code> instance, where previously they accepted a <code>RequestContext</code>.</p> </li> <li> <p>Admin request handlers now receive an <code>AdminRequestContext</code> as <code>app[\"context\"]</code>. The current profile is available as <code>app[\"context\"].profile</code>. The admin server now generates a unique context instance per request in order to facilitate multi-tenancy, rather than reusing the same instance for each handler.</p> </li> <li> <p>In order to inject the <code>BaseStorage</code> or <code>BaseWallet</code> interfaces, a <code>ProfileSession</code> must be used. Other interfaces can be injected at the <code>Profile</code> or <code>ProfileSession</code> level. This is obtained by awaiting <code>profile.session()</code> for the current <code>Profile</code> instance, or (preferably) using it as an async context manager:</p> </li> </ul> <p><code>python= async with profile.session() as session:    storage = session.inject(BaseStorage)</code></p> <ul> <li>The <code>inject</code> method of a context is no longer <code>async</code>.</li> </ul>"},{"location":"CHANGELOG/#056","title":"0.5.6","text":""},{"location":"CHANGELOG/#october-19-2020","title":"October 19, 2020","text":"<ul> <li>Fix an attempt to update the agent endpoint when configured with a read-only ledger #758</li> </ul>"},{"location":"CHANGELOG/#055","title":"0.5.5","text":""},{"location":"CHANGELOG/#october-9-2020","title":"October 9, 2020","text":"<ul> <li>Support interactions using the new <code>https://didcomm.org</code> message type prefix (currently opt-in via the <code>--emit-new-didcomm-prefix</code> flag) #705, #713</li> <li>Updates to application startup arguments, adding support for YAML configuration #739, #746, #748</li> <li>Add a new endpoint to check the revocation status of a stored credential #735</li> <li>Clean up API documentation and OpenAPI definition, minor API adjustments #712, #726, #732, #734, #738, #741, #747</li> <li>Add configurable support for unencrypted record tags #723</li> <li>Retain more limited records on issued credentials #718</li> <li>Fix handling of custom endpoint in connections <code>accept-request</code> API method #715,   #716</li> <li>Add restrictions around revocation registry sizes #727</li> <li>Allow the state for revocation registry records to be set manually #708</li> <li>Handle multiple matching credentials when satisfying a presentation request using <code>names</code> #706</li> <li>Additional handling for a missing local tails file, tails file rollover process #702, #717</li> <li>Handle unknown credential ID in <code>create-proof</code> API method #700</li> <li>Improvements to revocation interval handling in presentation requests #699, #703</li> <li>Clean up warnings on API redirects #692</li> <li>Extensions to DID publicity status #691</li> <li>Support Unicode text in JSON-LD credential handling #687</li> </ul>"},{"location":"CHANGELOG/#054","title":"0.5.4","text":""},{"location":"CHANGELOG/#august-24-2020","title":"August 24, 2020","text":"<ul> <li>Improvements to schema, cred def registration procedure #682, #683</li> <li>Updates to align admin API output with documented interface #674, #681</li> <li>Fix provisioning issue when ledger is configured as read-only #673</li> <li>Add <code>get-nym-role</code> action #671</li> <li>Basic support for w3c profile endpoint #667, #669</li> <li>Improve handling of non-revocation interval #648, #680</li> <li>Update revocation demo after changes to tails file handling #644</li> <li>Improve handling of fatal ledger errors #643, #659</li> <li>Improve <code>did:key:</code> handling in out-of-band protocol support #639</li> <li>Fix crash when no public DID is configured #637</li> <li>Fix high CPU usage when only messages pending retry are in the outbound queue #636</li> <li>Additional unit tests for config, messaging, revocation, startup, transports #633, #641, #658, #661, #666</li> <li>Allow forwarded messages to use existing connections and the outbound queue #631</li> </ul>"},{"location":"CHANGELOG/#053","title":"0.5.3","text":""},{"location":"CHANGELOG/#july-23-2020","title":"July 23, 2020","text":"<ul> <li>Store endpoint on provisioned DID records #610</li> <li>More reliable delivery of outbound messages and webhooks #615</li> <li>Improvements for OpenShift pod handling #614</li> <li>Remove support for 'on-demand' revocation registries #605</li> <li>Sort tags in generated swagger JSON for better consistency #602</li> <li>Improve support for multi-credential proofs #601</li> <li>Adjust default settings for tracing and add documentation #598, #597</li> <li>Fix reliance on local copy of revocation tails file #590</li> <li>Improved handling of problem reports #595</li> <li>Remove credential preview parameter from credential issue endpoint #596</li> <li>Looser format restrictions on dates #586</li> <li>Support <code>names</code> and attribute-value specifications in present-proof protocol #587</li> <li>Misc documentation updates and unit test coverage</li> </ul>"},{"location":"CHANGELOG/#052","title":"0.5.2","text":""},{"location":"CHANGELOG/#june-26-2020","title":"June 26, 2020","text":"<ul> <li>Initial out-of-band protocol support #576</li> <li>Support provisioning a new local-only DID in the wallet, updating a DID endpoint #559, #573</li> <li>Support pagination for holder search operation #558</li> <li>Add raw JSON credential signing and verification admin endpoints #540</li> <li>Catch fatal errors in admin and protocol request handlers #527, #533, #534, #539, #543, #554, #555</li> <li>Add wallet and DID key rotation operations #525</li> <li>Admin API documentation and usability improvements #504, #516, #570</li> <li>Adjust the maximum number of attempts for outbound messages #501</li> <li>Add demo support for tails server #499</li> <li>Various credential and presentation protocol fixes and improvements #491, #494, #498, #526, #561, #563, #564, #577, #579</li> <li>Fixes for multiple agent endpoints #495, #497</li> <li>Additional test coverage #482, #485, #486, #487, #490, #493, #509, #553</li> <li>Update marshmallow dependency #479</li> </ul>"},{"location":"CHANGELOG/#051","title":"0.5.1","text":""},{"location":"CHANGELOG/#april-23-2020","title":"April 23, 2020","text":"<ul> <li>Restore previous response format for the <code>/credential/{id}</code> admin route #474</li> </ul>"},{"location":"CHANGELOG/#050","title":"0.5.0","text":""},{"location":"CHANGELOG/#april-21-2020","title":"April 21, 2020","text":"<ul> <li>Add support for credential revocation and revocation registry handling, with thanks to Medici Ventures #306, #417, #425, #429, #432, #435, #441, #455</li> <li>Breaking change Remove previous credential and presentation protocols (0.1 versions) #416</li> <li>Add support for major/minor protocol version routing #443</li> <li>Event tracing and trace reports for message exchanges #440</li> <li>Support additional Indy restriction operators (<code>&gt;</code>, <code>&lt;</code>, <code>&lt;=</code> in addition to <code>&gt;=</code>) #457</li> <li>Support signed attachments according to the updated Aries RFC 0017 #456</li> <li>Increased test coverage #442, #453</li> <li>Updates to demo agents and documentation #402, #403, #411, #415, #422, #423, #449, #450, #452</li> <li>Use Indy generate_nonce method to create proof request nonces #431</li> <li>Make request context available in the outbound transport handler #408</li> <li>Contain indy-anoncreds usage in IndyIssuer, IndyHolder, IndyProver classes #406, #463</li> <li>Fix issue with validation of proof with predicates and revocation support #400</li> </ul>"},{"location":"CHANGELOG/#045","title":"0.4.5","text":""},{"location":"CHANGELOG/#march-3-2020","title":"March 3, 2020","text":"<ul> <li>Added NOTICES file with license information for dependencies #398</li> <li>Updated documentation for administration API demo #397</li> <li>Accept self-attested attributes in presentation verification, only when no restrictions are present on the requested attribute #394, #396</li> </ul>"},{"location":"CHANGELOG/#044","title":"0.4.4","text":""},{"location":"CHANGELOG/#february-28-2020","title":"February 28, 2020","text":"<ul> <li>Update docker image used in demo and test containers #391</li> <li>Fix pre-verify check on received presentations #390</li> <li>Do not canonicalize attribute names in credential previews #389</li> </ul>"},{"location":"CHANGELOG/#043","title":"0.4.3","text":""},{"location":"CHANGELOG/#february-26-2020","title":"February 26, 2020","text":"<ul> <li>Fix the application of transaction author agreement acceptance to signed ledger requests #385</li> <li>Add a command line argument to preserve connection exchange records #355</li> <li>Allow custom credential IDs to be specified by the controller in the issue-credential protocol #384</li> <li>Handle send timeouts in the admin server websocket implementation #377</li> <li>Aries RFC 0348: Support the 'didcomm.org' message type prefix for incoming messages #379</li> <li>Add support for additional postgres wallet schemes such as \"MultiWalletDatabase\" #378</li> <li>Updates to the demo agents and documentation to support demos using the OpenAPI interface #371, #375, #376, #382, #383, #382</li> <li>Add a new flag for preventing writes to the ledger #364</li> </ul>"},{"location":"CHANGELOG/#042","title":"0.4.2","text":""},{"location":"CHANGELOG/#february-8-2020","title":"February 8, 2020","text":"<ul> <li>Adjust logging on HTTP request retries #363</li> <li>Tweaks to <code>run_docker</code>/<code>run_demo</code> scripts for Windows #357</li> <li>Avoid throwing exceptions on invalid or incomplete received presentations #359</li> <li>Restore the <code>present-proof/create-request</code> admin endpoint for creating connectionless presentation requests #356</li> <li>Activate the <code>connections/create-static</code> admin endpoint for creating static connections #354</li> </ul>"},{"location":"CHANGELOG/#041","title":"0.4.1","text":""},{"location":"CHANGELOG/#january-31-2020","title":"January 31, 2020","text":"<ul> <li>Update Forward messages and handlers to align with RFC 0094 for compatibility with libvcx and Streetcred #240, #349</li> <li>Verify encoded attributes match raw attributes on proof presentation #344</li> <li>Improve checks for existing credential definitions in the wallet and on ledger when publishing #333, #346</li> <li>Accommodate referents in presentation proposal preview attribute specifications #333</li> <li>Make credential proposal optional in issue-credential protocol #336</li> <li>Handle proofs with repeated credential definition IDs #330</li> <li>Allow side-loading of alternative inbound transports #322</li> <li>Various fixes to documentation and message schemas, and improved unit test coverage</li> </ul>"},{"location":"CHANGELOG/#040","title":"0.4.0","text":""},{"location":"CHANGELOG/#december-10-2019","title":"December 10, 2019","text":"<ul> <li>Improved unit test coverage (actionmenu, basicmessage, connections, introduction, issue-credential, present-proof, routing protocols)</li> <li>Various documentation and bug fixes</li> <li>Add admin routes for fetching and accepting the ledger transaction author agreement #144</li> <li>Add support for receiving connection-less proof presentations #296</li> <li>Set attachment id explicitly in unbound proof request #289</li> <li>Add create-proposal admin endpoint to the present-proof protocol #288</li> <li>Remove old anon/authcrypt support #282</li> <li>Allow additional endpoints to be specified #276</li> <li>Allow timestamp without trailing 'Z' #275, #277</li> <li>Display agent label and version on CLI and SwaggerUI #274</li> <li>Remove connection activity tracking and add ping webhooks (with --monitor-ping) #271</li> <li>Refactor message transport to track all async tasks, active message handlers #269, #287</li> <li>Add invitation mode \"static\" for static connections #260</li> <li>Allow for cred proposal underspecification of cred def id, only lock down cred def id at issuer on offer. Sync up api requests to Aries RFC-36 verbiage #259</li> <li>Disable cookies on outbound requests (avoid session affinity) #258</li> <li>Add plugin registry for managing all loaded protocol plugins, streamline ClassLoader #257, #261</li> <li>Add support for locking a cache key to avoid repeating expensive operations #256</li> <li>Add optional support for uvloop #255</li> <li>Output timing information when --timing-log argument is provided #254</li> <li>General refactoring - modules moved from messaging into new core, protocols, and utils sub-packages #250, #301</li> <li>Switch performance demo to the newer issue-credential protocol #243</li> </ul>"},{"location":"CHANGELOG/#035","title":"0.3.5","text":""},{"location":"CHANGELOG/#november-1-2019","title":"November 1, 2019","text":"<ul> <li>Switch performance demo to the newer issue-credential protocol #243</li> <li>Remove old method for reusing credential requests and replace with local caching for credential offers and requests #238, #242</li> <li>Add statistics on HTTP requests to timing output #237</li> <li>Reduce the number of tags on non-secrets records to reduce storage requirements and improve performance #235</li> </ul>"},{"location":"CHANGELOG/#034","title":"0.3.4","text":""},{"location":"CHANGELOG/#october-23-2019","title":"October 23, 2019","text":"<ul> <li>Clean up base64 handling in wallet utils and add tests #224</li> <li>Support schema sequence numbers for lookups and caching and allow credential definition tag override via admin API #223</li> <li>Support multiple proof referents in the present-proof protocol #222</li> <li>Group protocol command line arguments appropriately #217</li> <li>Don't require a signature for get_txn_request in credential_definition_id2schema_id and reduce public DID lookups #215</li> <li>Add a role property to credential exchange and presentation exchange records #214, #218</li> <li>Improve attachment decorator handling #210</li> <li>Expand and correct documentation of the OpenAPI interface #208, #212</li> </ul>"},{"location":"CHANGELOG/#033","title":"0.3.3","text":""},{"location":"CHANGELOG/#september-27-2019","title":"September 27, 2019","text":"<ul> <li>Clean up LGTM errors and warnings and fix a message dispatch error #203</li> <li>Avoid wrapping messages with Forward wrappers when returning them directly #199</li> <li>Add a CLI parameter to override the base URL used in URL-formatted connection invitations #197</li> <li>Update the feature discovery protocol to match the RFC and rename the admin API endpoint #193</li> <li>Add CLI parameters for specifying additional properties of the printed connection invitation #192</li> <li>Add support for explicitly setting the wallet credential ID on storage #188</li> <li>Additional performance tracking and storage reductions #187</li> <li>Handle connection invitations in base64 or URL format in the Alice demo agent #186</li> <li>Add admin API methods to get and set the credential tagging policy for a credential definition ID #185</li> <li>Allow querying of credentials for proof requests with multiple referents #181</li> <li>Allow self-connected agents to issue credentials, present proofs #179</li> <li>Add admin API endpoints to register a ledger nym, fetch a ledger DID verkey, or fetch a ledger DID endpoint #178</li> </ul>"},{"location":"CHANGELOG/#032","title":"0.3.2","text":""},{"location":"CHANGELOG/#september-3-2019","title":"September 3, 2019","text":"<ul> <li>Merge support for Aries #36 (issue-credential) and Aries #37 (present-proof) protocols #164, #167</li> <li>Add <code>initiator</code> to connection record queries to ensure uniqueness in the case of a self-connection #161</li> <li>Add connection aliases #149</li> <li>Misc documentation updates</li> </ul>"},{"location":"CHANGELOG/#031","title":"0.3.1","text":""},{"location":"CHANGELOG/#august-15-2019","title":"August 15, 2019","text":"<ul> <li>Do not fail with an error when no ledger is configured #145</li> <li>Switch to PyNaCl instead of pysodium; update dependencies #143</li> <li>Support reusable connection invitations #142</li> <li>Fix --version option and optimize Docker builds #136</li> <li>Add connection_id to basicmessage webhooks #134</li> <li>Fixes for transaction author agreements #133</li> </ul>"},{"location":"CHANGELOG/#030","title":"0.3.0","text":""},{"location":"CHANGELOG/#august-9-2019","title":"August 9, 2019","text":"<ul> <li>Ledger and wallet config updates; add support for transaction author agreements #127</li> <li>Handle duplicate schema in send_schema by always fetching first #126</li> <li>More flexible timeout support in detect_process #125</li> <li>Add start command to run_docker invocations #119</li> <li>Add issuer stored state #114</li> <li>Add admin route to create a presentation request without sending it #112</li> <li>Add -v option to aca-py executable to print version #110</li> <li>Fix demo presentation request, optimize credential retrieval #108</li> <li>Add pypi badge to README and make document link URLs absolute #103</li> <li>Add admin routes for creating and listing wallet DIDs, adjusting the public DID #102</li> <li>Update the running locally instructions based on feedback from Sam Smith #101</li> <li>Add support for multiple invocation commands, implement start/provision/help commands #99</li> <li>Add admin endpoint to send problem report #98</li> <li>Add credential received state transition #97</li> <li>Adding documentation for the routing version of the performance example #94</li> <li>Document listing the Aries RFCs supported by ACA-Py and reference to the list in the README #89</li> <li>Further updates to the running locally section of the demo README #86</li> <li>Don't extract decorators with names matching the 'data_key' of defined schema fields #85</li> <li>Allow demo scripts to run outside of Docker; add command line parsing #84</li> <li>Connection invitation fixes and improvements; support DID-based invitations #82</li> </ul>"},{"location":"CHANGELOG/#021","title":"0.2.1","text":""},{"location":"CHANGELOG/#july-16-2019","title":"July 16, 2019","text":"<ul> <li>Add missing MANIFEST file #78</li> </ul>"},{"location":"CHANGELOG/#020","title":"0.2.0","text":""},{"location":"CHANGELOG/#july-16-2019_1","title":"July 16, 2019","text":"<p>This is the first PyPI release. The history begins with the transfer of aca-py from bcgov to hyperledger.</p> <ul> <li>Prepare for version 0.2.0 release #77</li> <li>Update von-network related references. #74</li> <li>Fixed log_level arg, added validation error logging #73</li> <li>fix shell inconsistency #72</li> <li>further cleanup to the OpenAPI demo script #71</li> <li>Updates to invitation handling and performance test #68</li> <li>Api security #67</li> <li>Fix line endings on Windows #66</li> <li>Fix repository name in badge links #65</li> <li>Connection record is_ready refactor #64</li> <li>Fix API instructions for cred def id #58</li> <li>Updated API demo docs to use alice/faber scripts #54</li> <li>Updates to the readme for the demo to add PWD support #53</li> <li>Swallow empty input in demo scripts #51</li> <li>Set credential_exchange state when created from a cached credential request #49</li> <li>Check for readiness instead of activeness in credential admin routes #46</li> <li>Demo updates #43</li> <li>Misc fixes #42</li> <li>Readme updates #41</li> <li>Change installed \"binary\" name to aca-py #40</li> <li>Tweak in script to work under Linux; updates to readme for demo #33</li> <li>New routing example document, typo corrections #31</li> <li>More bad links #30</li> <li>Links cleanup for the documentation #29</li> <li>Alice-Faber demo update #28</li> <li>Deployment Model document #27</li> <li>Plantuml source and images for documentation; w/image generator script #26</li> <li>Move generated documentation. #25</li> <li>Update generated documents #24</li> <li>Split application configuration into separate modules and add tests #23</li> <li>Updates to the RTD configuration file #22</li> <li>Merge DIDDoc support from von_anchor #21</li> <li>Adding Prov of BC, Gov of Canada copyright #19</li> <li>Update test configuration #18</li> <li>CI updates #17</li> <li>Transport updates #15</li> </ul>"},{"location":"CODE_OF_CONDUCT/","title":"Hyperledger Code of Conduct","text":"<p>Hyperledger is a collaborative project at The Linux Foundation. It is an open-source and open community project where participants choose to work together, and in that process experience differences in language, location, nationality, and experience. In such a diverse environment, misunderstandings and disagreements happen, which in most cases can be resolved informally. In rare cases, however, behavior can intimidate, harass, or otherwise disrupt one or more people in the community, which Hyperledger will not tolerate.</p> <p>A Code of Conduct is useful to define accepted and acceptable behaviors and to promote high standards of professional practice. It also provides a benchmark for self evaluation and acts as a vehicle for better identity of the organization.</p> <p>This code (CoC) applies to any member of the Hyperledger community \u2013 developers, participants in meetings, teleconferences, mailing lists, conferences or functions, etc. Note that this code complements rather than replaces legal rights and obligations pertaining to any particular situation.</p>"},{"location":"CODE_OF_CONDUCT/#statement-of-intent","title":"Statement of Intent","text":"<p>Hyperledger is committed to maintain a positive work environment. This commitment calls for a workplace where participants at all levels behave according to the rules of the following code. A foundational concept of this code is that we all share responsibility for our work environment.</p>"},{"location":"CODE_OF_CONDUCT/#code","title":"Code","text":"<ol> <li> <p>Treat each other with respect, professionalism, fairness, and sensitivity to our many    differences and strengths, including in situations of high pressure and urgency.</p> </li> <li> <p>Never harass or bully anyone verbally, physically or    sexually.</p> </li> <li> <p>Never discriminate on the basis of personal characteristics or group    membership.</p> </li> <li> <p>Communicate constructively and avoid demeaning or    insulting behavior or language.</p> </li> <li> <p>Seek, accept, and offer objective work criticism, and acknowledge properly    the contributions of others.</p> </li> <li> <p>Be honest about your own qualifications, and about any circumstances that might lead to conflicts    of interest.</p> </li> <li> <p>Respect the privacy of others and the confidentiality of data you access.</p> </li> <li> <p>With respect to cultural differences, be conservative in what you do and liberal in what you    accept from others, but not to the point of accepting disrespectful, unprofessional or unfair or    unwelcome behavior or advances.</p> </li> <li> <p>Promote the rules of this Code and take action (especially if you are in a    leadership position) to bring the discussion back to a more civil level    whenever inappropriate behaviors are observed.</p> </li> <li> <p>Stay on topic: Make sure that you are posting to the correct channel and avoid off-topic     discussions. Remember when you update an issue or respond to an email you are potentially     sending to a large number of people.</p> </li> <li> <p>Step down considerately: Members of every project come and go, and the Hyperledger is no     different. When you leave or disengage from the project, in whole or in part, we ask that you do     so in a way that minimizes disruption to the project. This means you should tell people you are     leaving and take the proper steps to ensure that others can pick up where you left off.</p> </li> </ol>"},{"location":"CODE_OF_CONDUCT/#glossary","title":"Glossary","text":""},{"location":"CODE_OF_CONDUCT/#demeaning-behavior","title":"Demeaning Behavior","text":"<p>is acting in a way that reduces another person's dignity, sense of self-worth or respect within the community.</p>"},{"location":"CODE_OF_CONDUCT/#discrimination","title":"Discrimination","text":"<p>is the prejudicial treatment of an individual based on criteria such as: physical appearance, race, ethnic origin, genetic differences, national or social origin, name, religion, gender, sexual orientation, family or health situation, pregnancy, disability, age, education, wealth, domicile, political view, morals, employment, or union activity.</p>"},{"location":"CODE_OF_CONDUCT/#insulting-behavior","title":"Insulting Behavior","text":"<p>is treating another person with scorn or disrespect.</p>"},{"location":"CODE_OF_CONDUCT/#acknowledgement","title":"Acknowledgement","text":"<p>is a record of the origin(s) and author(s) of a contribution.</p>"},{"location":"CODE_OF_CONDUCT/#harassment","title":"Harassment","text":"<p>is any conduct, verbal or physical, that has the intent or effect of interfering with an individual, or that creates an intimidating, hostile, or offensive environment.</p>"},{"location":"CODE_OF_CONDUCT/#leadership-position","title":"Leadership Position","text":"<p>includes group Chairs, project maintainers, staff members, and Board members.</p>"},{"location":"CODE_OF_CONDUCT/#participant","title":"Participant","text":"<p>includes the following persons:</p> <ul> <li>Developers</li> <li>Member representatives</li> <li>Staff members</li> <li>Anyone from the Public partaking in the Hyperledger work environment (e.g. contribute code,   comment on our code or specs, email us, attend our conferences, functions, etc)</li> </ul>"},{"location":"CODE_OF_CONDUCT/#respect","title":"Respect","text":"<p>is the genuine consideration you have for someone (if only because of their status as participant in Hyperledger, like yourself), and that you show by treating them in a polite and kind way.</p>"},{"location":"CODE_OF_CONDUCT/#sexual-harassment","title":"Sexual Harassment","text":"<p>includes visual displays of degrading sexual images, sexually suggestive conduct, offensive remarks of a sexual nature, requests for sexual favors, unwelcome physical contact, and sexual assault.</p>"},{"location":"CODE_OF_CONDUCT/#unwelcome-behavior","title":"Unwelcome Behavior","text":"<p>Hard to define? Some questions to ask yourself are:</p> <ul> <li>how would I feel if I were in the position of the recipient?</li> <li>would my spouse, parent, child, sibling or friend like to be treated this way?</li> <li>would I like an account of my behavior published in the organization's newsletter?</li> <li>could my behavior offend or hurt other members of the work group?</li> <li>could someone misinterpret my behavior as intentionally harmful or harassing?</li> <li>would I treat my boss or a person I admire at work like that ?</li> <li>Summary: if you are unsure whether something might be welcome or unwelcome, don't do it.</li> </ul>"},{"location":"CODE_OF_CONDUCT/#unwelcome-sexual-advance","title":"Unwelcome Sexual Advance","text":"<p>includes requests for sexual favors, and other verbal or physical conduct of a sexual nature, where:</p> <ul> <li>submission to such conduct is made either explicitly or implicitly a term or condition of an   individual's employment,</li> <li>submission to or rejection of such conduct by an individual is used as a basis for employment   decisions affecting the individual,</li> <li>such conduct has the purpose or effect of unreasonably interfering with an individual's work   performance or creating an intimidating hostile or offensive working environment.</li> </ul>"},{"location":"CODE_OF_CONDUCT/#workplace-bullying","title":"Workplace Bullying","text":"<p>is a tendency of individuals or groups to use persistent aggressive or unreasonable behavior (e.g. verbal or written abuse, offensive conduct or any interference which undermines or impedes work) against a co-worker or any professional relations.</p>"},{"location":"CODE_OF_CONDUCT/#work-environment","title":"Work Environment","text":"<p>is the set of all available means of collaboration, including, but not limited to messages to mailing lists, private correspondence, Web pages, chat channels, phone and video teleconferences, and any kind of face-to-face meetings or discussions.</p>"},{"location":"CODE_OF_CONDUCT/#incident-procedure","title":"Incident Procedure","text":"<p>To report incidents or to appeal reports of incidents, send email to Mike Dolan (mdolan@linuxfoundation.org) or Angela Brown (angela@linuxfoundation.org). Please include any available relevant information, including links to any publicly accessible material relating to the matter. Every effort will be taken to ensure a safe and collegial environment in which to collaborate on matters relating to the Project. In order to protect the community, the Project reserves the right to take appropriate action, potentially including the removal of an individual from any and all participation in the project. The Project will work towards an equitable resolution in the event of a misunderstanding.</p>"},{"location":"CODE_OF_CONDUCT/#credits","title":"Credits","text":"<p>This code is based on the W3C\u2019s Code of Ethics and Professional Conduct with some additions from the Cloud Foundry\u2018s Code of Conduct.</p>"},{"location":"CONTRIBUTING/","title":"How to contribute","text":"<p>You are encouraged to contribute to the repository by forking and submitting a pull request.</p> <p>For significant changes, please open an issue first to discuss the proposed changes to avoid re-work.</p> <p>(If you are new to GitHub, you might start with a basic tutorial and check out a more detailed guide to pull requests.)</p> <p>Pull requests will be evaluated by the repository guardians on a schedule and if deemed beneficial will be committed to the <code>main</code> branch. Pull requests should have a descriptive name, include a summary of all changes made in the pull request description, and include unit tests that provide good coverage of the feature or fix. A Continuous Integration (CI) pipeline is executed on all PRs before review and contributors are expected to address all CI issues identified. Where appropriate, PRs that impact the end-user and developer demos in the repo should include updates or extensions to those demos to cover the new capabilities.</p> <p>If you would like to propose a significant change, please open an issue first to discuss the work with the community.</p> <p>Contributions are made pursuant to the Developer's Certificate of Origin, available at https://developercertificate.org, and licensed under the Apache License, version 2.0 (Apache-2.0).</p>"},{"location":"CONTRIBUTING/#development-tools","title":"Development Tools","text":""},{"location":"CONTRIBUTING/#pre-commit","title":"Pre-commit","text":"<p>A configuration for pre-commit is included in this repository. This is an optional tool to help contributors commit code that follows the formatting requirements enforced by the CI pipeline. Additionally, it can be used to help contributors write descriptive commit messages that can be parsed by changelog generators.</p> <p>On each commit, pre-commit hooks will run that verify the committed code complies with ruff and is formatted with black. To install the ruff and black checks:</p> <pre><code>pre-commit install\n</code></pre> <p>To install the commit message linter:</p> <pre><code>pre-commit install --hook-type commit-msg\n</code></pre>"},{"location":"MAINTAINERS/","title":"Maintainers","text":""},{"location":"MAINTAINERS/#maintainer-scopes-github-roles-and-github-teams","title":"Maintainer Scopes, GitHub Roles and GitHub Teams","text":"<p>Maintainers are assigned the following scopes in this repository:</p> Scope Definition GitHub Role GitHub Team Admin Admin aries-admins Maintainer The GitHub Maintain role Maintain aries-cloudagent-python committers Triage The GitHub Triage role Triage aries triage Read The GitHub Read role Read Aries Contributors Read The GitHub Read role Read TOC Read The GitHub Read role Read aries-framework-go-ext committers"},{"location":"MAINTAINERS/#active-maintainers","title":"Active Maintainers","text":"GitHub ID Name Scope LFID Discord ID Email Company Affiliation andrewwhitehead Andrew Whitehead Admin cywolf@gmail.com BC Gov dbluhm Daniel Bluhm Admin daniel@indicio.tech Indicio PBC dhh1128 Daniel Hardman Admin daniel.hardman@gmail.com Provident shaangill025 Shaanjot Gill Maintainer gill.shaanjots@gmail.com BC Gov swcurran Stephen Curran Admin swcurran@cloudcompass.ca BC Gov TelegramSam Sam Curren Maintainer telegramsam@gmail.com Indicio PBC TimoGlastra Timo Glastra Admin timo@animo.id Animo Solutions WadeBarnes Wade Barnes Admin wade@neoterictech.ca BC Gov usingtechnology Jason Sherman Maintainer tools@usingtechnolo.gy BC Gov"},{"location":"MAINTAINERS/#emeritus-maintainers","title":"Emeritus Maintainers","text":"Name GitHub ID Scope LFID Discord ID Email Company Affiliation"},{"location":"MAINTAINERS/#the-duties-of-a-maintainer","title":"The Duties of a Maintainer","text":"<p>Maintainers are expected to perform the following duties for this repository. The duties are listed in more or less priority order:</p> <ul> <li>Review, respond, and act on any security vulnerabilities reported against the repository.</li> <li>Review, provide feedback on, and merge or reject GitHub Pull Requests from   Contributors.</li> <li>Review, triage, comment on, and close GitHub Issues   submitted by Contributors.</li> <li>When appropriate, lead/facilitate architectural discussions in the community.</li> <li>When appropriate, lead/facilitate the creation of a product roadmap.</li> <li>Create, clarify, and label issues to be worked on by Contributors.</li> <li>Ensure that there is a well defined (and ideally automated) product test and   release pipeline, including the publication of release artifacts.</li> <li>When appropriate, execute the product release process.</li> <li>Maintain the repository CONTRIBUTING.md file and getting started documents to   give guidance and encouragement to those wanting to contribute to the product, and those wanting to become maintainers.</li> <li>Contribute to the product via GitHub Pull Requests.</li> <li>Monitor requests from the Hyperledger Technical Oversight Committee about the contents and management of Hyperledger repositories, such as branch handling, required files in repositories and so on.</li> <li>Contribute to the Hyperledger Project's Quarterly Report.</li> </ul>"},{"location":"MAINTAINERS/#becoming-a-maintainer","title":"Becoming a Maintainer","text":"<p>This community welcomes contributions. Interested contributors are encouraged to progress to become maintainers. To become a maintainer the following steps occur, roughly in order.</p> <ul> <li>The proposed maintainer establishes their reputation in the community,   including authoring five (5) significant merged pull requests, and expresses   an interest in becoming a maintainer for the repository.</li> <li>A PR is created to update this file to add the proposed maintainer to the list of active maintainers.</li> <li>The PR is authored by an existing maintainer or has a comment on the PR from an existing maintainer supporting the proposal.</li> <li>The PR is authored by the proposed maintainer or has a comment on the PR from the proposed maintainer confirming their interest in being a maintainer.</li> <li>The PR or comment from the proposed maintainer must include their     willingness to be a long-term (more than 6 month) maintainer.</li> <li>Once the PR and necessary comments have been received, an approval timeframe begins.</li> <li>The PR MUST be communicated on all appropriate communication channels, including relevant community calls, chat channels and mailing lists. Comments of support from the community are welcome.</li> <li>The PR is merged and the proposed maintainer becomes a maintainer if either:</li> <li>Two weeks have passed since at least three (3) Maintainer PR approvals have been recorded, OR</li> <li>An absolute majority of maintainers have approved the PR.</li> <li>If the PR does not get the requisite PR approvals, it may be closed.</li> <li>Once the add maintainer PR has been merged, any necessary updates to the GitHub Teams are made.</li> </ul>"},{"location":"MAINTAINERS/#removing-maintainers","title":"Removing Maintainers","text":"<p>Being a maintainer is not a status symbol or a title to be carried indefinitely. It will occasionally be necessary and appropriate to move a maintainer to emeritus status. This can occur in the following situations:</p> <ul> <li>Resignation of a maintainer.</li> <li>Violation of the Code of Conduct warranting removal.</li> <li>Inactivity.</li> <li>A general measure of inactivity will be no commits or code review comments     for one reporting quarter. This will not be strictly enforced if     the maintainer expresses a reasonable intent to continue contributing.</li> <li>Reasonable exceptions to inactivity will be granted for known long term     leave such as parental leave and medical leave.</li> <li>Other circumstances at the discretion of the other Maintainers.</li> </ul> <p>The process to move a maintainer from active to emeritus status is comparable to the process for adding a maintainer, outlined above. In the case of voluntary resignation, the Pull Request can be merged following a maintainer PR approval. If the removal is for any other reason, the following steps SHOULD be followed:</p> <ul> <li>A PR is created to update this file to move the maintainer to the list of emeritus maintainers.</li> <li>The PR is authored by, or has a comment supporting the proposal from, an existing maintainer or Hyperledger GitHub organization administrator.</li> <li>Once the PR and necessary comments have been received, the approval timeframe begins.</li> <li>The PR MAY be communicated on appropriate communication channels, including relevant community calls, chat channels and mailing lists.</li> <li>The PR is merged and the maintainer transitions to maintainer emeritus if:</li> <li>The PR is approved by the maintainer to be transitioned, OR</li> <li>Two weeks have passed since at least three (3) Maintainer PR approvals have been recorded, OR</li> <li>An absolute majority of maintainers have approved the PR.</li> <li>If the PR does not get the requisite PR approvals, it may be closed.</li> </ul> <p>Returning to active status from emeritus status uses the same steps as adding a new maintainer. Note that the emeritus maintainer already has the 5 required significant changes as there is no contribution time horizon for those.</p>"},{"location":"PUBLISHING/","title":"How to Publish a New Version","text":"<p>The code to be published should be in the <code>main</code> branch. Make sure that all the PRs to go in the release are merged, and decide on the release tag. Should it be a release candidate or the final tag, and should it be a major, minor or patch release, per semver rules.</p> <p>Once ready to do a release, create a local branch that includes the following updates:</p> <ol> <li> <p>Create a PR branch from an updated <code>main</code> branch.</p> </li> <li> <p>Update the CHANGELOG.md to add the new release.  Only create a new section when working on the first release candidate for a new release. When transitioning from one release candidate to the next, or to an official release, just update the title and date of the change log section.</p> </li> <li> <p>Include details of the merged PRs included in this release. General process to follow:</p> </li> <li> <p>Gather the set of PRs since the last release and put them into a list. A good   tool to use for this is the   github-changelog-generator.   Steps:</p> </li> <li>Create a read only GitHub token for your account on this page:     https://github.com/settings/tokens     with a scope of <code>repo</code> / <code>public_repo</code>.</li> <li>Use a command like the following, adjusting the tag parameters as     appropriate. <code>docker run -it --rm -v \"$(pwd)\":/usr/local/src/your-app     githubchangeloggenerator/github-changelog-generator --user hyperledger     --project aries-cloudagent-python --output 0.11.0rc2.md --since-tag 0.10.4     --future-release 0.11.1rc2 --release-branch main --token &lt;your-token&gt;</code></li> <li>In the generated file, use only the PR list -- we don't include the list of     closed issues in the Change Log.</li> </ol> <p>In some cases, the approach above fails because of too many API calls. An alternate approach to getting the list of PRs in the right format is to use OpenAI ChatGPT.</p> <p>Prepare the following ChatGPT request. Don't hit enter yet--you have to add the data.</p> <p><code>Generate from this the github pull request number, the github id of the author and the title of the pull request in a tab-delimited list</code></p> <p>Get a list of the merged PRs since the last release by displaying the PR list in the GitHub UI, highlighting/copying the PRs and pasting them below the ChatGPT request, one page after another. Hit <code>&lt;Enter&gt;</code>, let the AI magic work, and you should have a list of the PRs in a nice table with a <code>Copy</code> link that you should click.</p> <p>Once you have that, open this Google Sheet and highlight the <code>A1</code> cell and paste in the ChatGPT data. A formula in column <code>E</code> will have the properly formatted changelog entries. Double check the list with the GitHub UI to make sure that ChatGPT isn't messing with you and you have the needed data.</p> <p>If using ChatGPT doesn't appeal to you, try this scary <code>sed</code>/command line approach:</p> <ul> <li>Put the following commands into a file called <code>changelog.sed</code></li> </ul> <pre><code>/Approved/d\n/updated /d\n/^$/d\n/^ [0-9]/d\ns/was merged.*//\n/^@/d\ns# by \\(.*\\) # [\\1](https://github.com/\\1)#\ns/^ //\ns#  \\#\\([0-9]*\\)# [\\#\\1](https://github.com/hyperledger/aries-cloudagent-python/pull/\\1) #\ns/  / /g\n/^Version/d\n/tasks done/d\ns/^/- /\n</code></pre> <ul> <li>Navigate in your browser to the paged list of PRs merged since the last   release (using in the GitHub UI a filter such as <code>is:pr is:merged sort:updated   merged:&gt;2022-04-07</code>) and for each page, highlight, and copy the text   of only the list of PRs on the page to use in the following step.</li> <li>For each page, run the command   <code>sed -e :a -e '$!N;s/\\n#/ #/;ta' -e 'P;D' &lt;&lt;EOF | sed -f changelog.sed</code>,   paste in the copied text and then type <code>EOF</code>.   Redirect the output to a file, appending each page of output to the file.</li> <li>The first <code>sed</code> command in the pipeline merges the PR title and PR number     plus author lines onto a single line. The commands in the <code>changelog.sed</code>     file just clean up the data, removing unwanted lines, etc.</li> <li>At the end of that process, you should have a list of all of the PRs in a form you can   use in the CHANGELOG.md file.</li> <li>To verify you have right number of PRs, you can do a <code>wc</code> of the file and there   should be one line per PR. You should scan the file as well, looking for   anomalies, such as missing <code>\\</code>s before <code>#</code> characters. It's a pretty ugly process.</li> <li>Using a <code>curl</code> command and the GitHub API is probably a much better and more   robust way to do this, but this was quick and dirty...</li> </ul> <p>Once you have the list of PRs:</p> <ul> <li>Organize the list into suitable categories, update (if necessary) the PR description and add notes to clarify the changes. See previous release entries to understand the style -- a format that should help developers.</li> <li> <p>Add a narrative about the release above the PR that highlights what has gone into the release.</p> </li> <li> <p>Check to see if there are any other PRs that should be included in the release.</p> </li> <li> <p>Update the ReadTheDocs in the <code>/docs</code> folder by following the instructions in    the <code>./README.md</code> file. That will likely add a number of new and modified    files to the PR. Eliminate all of the errors in the generation process,    either by mocking external dependencies or by fixing ACA-Py code. If    necessary, create an issue with the errors and assign it to the appropriate    developer. Experience has demonstrated to use that documentation generation    errors should be fixed in the code.</p> </li> <li> <p>Search across the repository for the previous version number and update it    everywhere that makes sense. The CHANGELOG.md is a likely exception, and the    <code>pyproject.toml</code> in the root is MUST. You can skip (although it won't    hurt) to update the files in the <code>open-api</code> folder as they will be    automagically updated by the next step in publishing. The incremented version    number MUST adhere to the Semantic Versioning    Specification    based on the changes since the last published release. For Release    Candidates, the form of the tag is \"0.11.0rc2\". As of release <code>0.11.0</code> we    have dropped the previously used <code>-</code> in the release candidate version string    to better follow the semver rules.</p> </li> <li> <p>Regenerate openapi.json and swagger.json by running    <code>./scripts/generate-open-api-spec</code>.</p> </li> <li> <p>Double check all of these steps above, and then submit a PR from the branch.    Add this new PR to CHANGELOG.md so that all the PRs are included.    If there are still further changes to be merged, mark the PR as \"Draft\",    repeat ALL of the steps again, and then mark this PR as ready and then    wait until it is merged. It's embarrassing when you have to do a whole new    release just because you missed something silly...I know!</p> </li> <li> <p>Immediately after it is merged, create a new GitHub tag representing the    version. The tag name and title of the release should be the same as the    version in pyproject.toml. Use    the \"Generate Release Notes\" capability to get a sequential listing of the    PRs in the release, to complement the manually curated Changelog. Verify on    PyPi that the version is published.</p> </li> <li> <p>New images for the release are automatically published by the GitHubAction    Workflows: publish.yml and publish-indy.yml. The actions are triggered    when a release is tagged, so no manual action is needed. The images are    published in the Hyperledger Package Repository under    aries-cloudagent-python    and a link to the packages added to the repositories main page (under    \"Packages\").</p> </li> </ul> <p>Additional information about the container image publication process can be    found in the document Container Images and Github Actions.</p> <ol> <li> <p>Update the ACA-Py Read The Docs site by building the new \"latest\" (main     branch) and activating and building the new release. Appropriate permissions     are required to publish the new documentation version.</p> </li> <li> <p>Update the https://aca-py.org website with the latest documentation by     creating a PR and tag of the latest documentation from this site. Details     are provided in the aries-acapy-docs repository.</p> </li> </ol>"},{"location":"SECURITY/","title":"Hyperledger Security Policy","text":""},{"location":"SECURITY/#reporting-a-security-bug","title":"Reporting a Security Bug","text":"<p>If you think you have discovered a security issue in any of the Hyperledger projects, we'd love to hear from you. We will take all security bugs seriously and if confirmed upon investigation we will patch it within a reasonable amount of time and release a public security bulletin discussing the impact and credit the discoverer.</p> <p>There are two ways to report a security bug. The easiest is to email a description of the flaw and any related information (e.g. reproduction steps, version) to security at hyperledger dot org.</p> <p>The other way is to file a confidential security bug in our JIRA bug tracking system. Be sure to set the \u201cSecurity Level\u201d to \u201cSecurity issue\u201d.</p> <p>The process by which the Hyperledger Security Team handles security bugs is documented further in our Defect Response page on our wiki.</p>"},{"location":"UpdateRTD/","title":"Managing Aries Cloud Agent Python <code>Read The Docs</code> Documentation","text":"<p>This document describes how to maintain the <code>Read The Docs</code> documentation that is generated from the ACA-Py code base. As the structure of the ACA-Py code evolves, the RTD files need to be regenerated and possibly updated, as described here.</p>"},{"location":"UpdateRTD/#generating-aca-py-read-the-docs-rtd-documentation","title":"Generating ACA-Py Read The Docs (RTD) documentation","text":""},{"location":"UpdateRTD/#before-you-start","title":"Before you start","text":"<p>To test generate and view the RTD documentation locally, you must install Sphinx and the Sphinx RTD theme. Follow the instructions on the respective pages to install and verify the installation on your system.</p>"},{"location":"UpdateRTD/#generate-module-files","title":"Generate Module Files","text":"<p>To rebuild the project and settings from scratch (you'll need to move the generated index file up a level):</p> <p><code>rm -rf generated; sphinx-apidoc -f -M -o  ./generated ../aries_cloudagent/ $(find ../aries_cloudagent/ -name '*tests*')</code></p> <p>Note that the <code>find</code> command that is used to exclude any of the <code>test</code> python files from the RTD documentation.</p> <p>Check the  <code>git status</code> in your repo to see if the generator updates, adds or removes any existing RTD modules.</p>"},{"location":"UpdateRTD/#reviewing-the-files-locally","title":"Reviewing the files locally","text":"<p>To auto-generate the module documentation locally run:</p> <pre><code>sphinx-build -b html -a -E -c ./ ./ ./_build\n</code></pre> <p>Once generated, go into the <code>_build</code> folder and open <code>index.html</code> in a browser. Note that the <code>_build</code> is <code>.gitignore</code>'d and so will not be part of a git push.</p>"},{"location":"UpdateRTD/#look-for-errors","title":"Look for Errors","text":"<p>This is the hard part; looking for errors in docstrings added by devs. Some tips:</p> <ul> <li>missing imports (<code>No module named 'async_timeout'</code>) can be solved by adding the module to the list of <code>autodoc_mock_imports</code> in the <code>conf.py</code> file in the ACA-Py <code>docs</code> folder.</li> <li>Ignore any errors in .md files</li> <li>Ignore the warnings about including <code>docs/README.md</code></li> <li>Ignore an dist-package errors</li> </ul> <p>Other than that, please investigate and fix things that you find. If there are fixes, it's usually to adhere to the rules around processing docstrings, and especially around JSON samples.</p>"},{"location":"UpdateRTD/#checking-for-missing-modules","title":"Checking for missing modules","text":"<p>The file <code>index.rst</code> in the ACA-Py <code>docs</code> folder drive the RTD generation. It picks up all the modules in the source code, starting from the root <code>../aries_cloudagent</code> folder. However, some modules are not picked up automatically from the root and have to be manually added to <code>index.rst</code>. To do that:</p> <ul> <li>Get a list of all generated modules by running: <code>ls generated | grep \"aries_cloudagent.[a-z]*.rst\"</code></li> <li>Compare that list with the modules listed in the \"Subpackages\" section of the left side menu in your browser, including any listed below the \"Submodules\".</li> </ul> <p>If any are missing, you likely need to add them to the <code>index.rst</code> file in the <code>toctree</code> section of the file. You will see there are already several instances of that, notably \"connections\" and \"protocols\".</p>"},{"location":"UpdateRTD/#updating-the-readthedocsorg-site","title":"Updating the readthedocs.org site","text":"<p>The RTD documentation is not currently auto-generated, so a manual re-generation of the documentation is still required.</p> <p>TODO: Automate this when new tags are applied to the repository.</p>"},{"location":"aca-py.org/","title":"Welcome!","text":"<p>Welcome to the Aries Cloud Agent Python documentation site. On this site you will find documentation for recent releases of ACA-Py. You'll find a few of the older versions of ACA-Py (pre-<code>0.8.0</code>), all versions since <code>0.8.0</code>, and the <code>main</code> branch, which is the latest and greatest.</p> <p>All of the documentation here is extracted from the Aries Cloud Agent Python repository. If you want to contribute to the documentation, please start there.</p> <p>Ready to go? Scan the tabs in the page header to find the documentation you need now!</p>"},{"location":"aca-py.org/#code-internals-documentation","title":"Code Internals Documentation","text":"<p>In addition to this documentation site, the ACA-Py community also maintains an ACA-Py internals documentation site. The internals documentation consists of the <code>docstrings</code> extracted from the ACA-Py Python code and covers all of the (non-test) modules in the codebase. Check it out on the Aries Cloud Agent-Python ReadTheDocs site. As with this site, the ReadTheDocs documentation is version specific.</p> <p>Got questions?</p> <ul> <li>Join us on the Hyperledger Discord Server, in the <code>#aries-cloudagent-python</code> channel.</li> <li>Add an issue in the Aries Cloud Agent Python repository.</li> </ul>"},{"location":"assets/","title":"Assets Folder for Documentation","text":"<p>Put any assets (images, source for images, videos, etc.) in this folder to be referenced in the various documents for this repo.</p>"},{"location":"assets/#plantuml-source-and-images","title":"Plantuml Source and Images","text":"<p>Plantuml diagrams are stored in this folder in source form in files ending in <code>.puml</code> and are generated manually using the <code>./genPlantuml</code> script. The script uses a docker image from docker-hub and can be run without downloading any dependencies.</p> <p>If you don't want to use the script, download plantuml and a command line utility and use that for the plantuml generation. I preferred not having any dependencies used (other than docker) and couldn't find a nice way to run plantuml headless from a command line.</p>"},{"location":"assets/#to-do","title":"To Do","text":"<p>It would be better to use a local <code>Dockerfile</code> vs. one found on Docker Hub. The one I did find was simple and straight forward.</p> <p>I couldn't tell if the svg generation was working so just went with png. Not sure which would be better.</p>"},{"location":"demo/","title":"Aries Cloud Agent Python (ACA-Py) Demos","text":"<p>There are several demos available for ACA-Py mostly (but not only) aimed at developers learning how to deploy an instance of the agent and an ACA-Py controller to implement an application.</p>"},{"location":"demo/#table-of-contents","title":"Table of Contents","text":"<ul> <li>The Alice/Faber Python demo</li> <li>Running in a Browser</li> <li>Running in Docker</li> <li>Running Locally<ul> <li>Installing Prerequisites</li> <li>Start a local Indy ledger</li> <li>Genesis File handling</li> <li>Run a local Postgres instance</li> <li>Optional: Run a von-network ledger browser</li> <li>Run the Alice and Faber Controllers/Agents</li> </ul> </li> <li>Follow The Script<ul> <li>Exchanging Messages</li> <li>Issuing and Proving Credentials</li> </ul> </li> <li>Additional Options in the Alice/Faber demo</li> <li>Revocation</li> <li>DID Exchange</li> <li>Endorser</li> <li>Run Indy-SDK Backend</li> <li>Mediation</li> <li>Multi-ledger</li> <li>Multi-tenancy</li> <li>Multi-tenancy with Mediation!!!</li> <li>Other Environment Settings</li> <li>Learning about the Alice/Faber code</li> <li>OpenAPI (Swagger) Demo</li> <li>Performance Demo</li> <li>Coding Challenge: Adding ACME</li> </ul>"},{"location":"demo/#the-alicefaber-python-demo","title":"The Alice/Faber Python demo","text":"<p>The Alice/Faber demo is the (in)famous first verifiable credentials demo. Alice, a former student of Faber College (\"Knowledge is Good\"), connects with the College, is issued a credential about her degree and then is asked by the College for a proof. There are a variety of ways of running the demo. The easiest is in your browser using a site (\"Play with VON\") that let's you run docker containers without installing anything. Alternatively, you can run locally on docker (our recommendation), or using python on your local machine. Each approach is covered below.</p>"},{"location":"demo/#running-in-a-browser","title":"Running in a Browser","text":"<p>In your browser, go to the docker playground service Play with Docker. On the title screen, click \"Start\". On the next screen, click (in the left menu) \"+Add a new instance\".  That will start up a terminal in your browser. Run the following commands to start the Faber agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber\n</code></pre> <p>Now to start Alice's agent. Click the \"+Add a new instance\" button again to open another terminal session. Run the following commands to start Alice's agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice\n</code></pre> <p>Alice's agent is now running.</p> <p>Jump to the Follow the Script section below for further instructions.</p>"},{"location":"demo/#running-in-docker","title":"Running in Docker","text":"<p>Running the demo in docker requires having a <code>von-network</code> (a Hyperledger Indy public ledger sandbox) instance running in docker locally. See the VON Network Tutorial for guidance on starting and stopping your own local Hyperledger Indy instance.</p> <p>Open three <code>bash</code> shells. For Windows users, <code>git-bash</code> is highly recommended. bash is the default shell in Linux and Mac terminal sessions.</p> <p>In the first terminal window, start <code>von-network</code> by following the Building and Starting instructions.</p> <p>In the second terminal, change directory into <code>demo</code> directory of your clone of the Aries Cloud Agent Python repository. Start the <code>faber</code> agent by issuing the following command:</p> <pre><code>  ./run_demo faber\n</code></pre> <p>In the third terminal, change directory into <code>demo</code> directory of your clone of the Aries Cloud Agent Python repository. Start the <code>alice</code> agent by issuing the following command:</p> <pre><code>  ./run_demo alice\n</code></pre> <p>Jump to the Follow the Script section below for further instructions.</p>"},{"location":"demo/#running-locally","title":"Running Locally","text":"<p>The following is an approach to to running the Alice and Faber demo using Python3 running on a bare machine. There are other ways to run the components, but this covers the general approach.</p> <p>We don't recommend this approach if you are just trying this demo, as you will likely run into issues with the specific setup of your machine.</p>"},{"location":"demo/#installing-prerequisites","title":"Installing Prerequisites","text":"<p>We assume you have a running Python 3 environment.  To install the prerequisites specific to running the agent/controller examples in your Python environment, run the following command from this repo's <code>demo</code> folder. The precise command to run may vary based on your Python environment setup.</p> <pre><code>pip3 install -r demo/requirements.txt\n</code></pre> <p>While that process will include the installation of the Indy python prerequisite, you still have to build and install the <code>libindy</code> code for your platform. Follow the installation instructions in the indy-sdk repo for your platform.</p>"},{"location":"demo/#start-a-local-indy-ledger","title":"Start a local Indy ledger","text":"<p>Start a local <code>von-network</code> Hyperledger Indy network running in Docker by following the VON Network Building and Starting instructions.</p> <p>We strongly recommend you use Docker for the local Indy network until you really, really need to know the details of running an Indy Node instance on a bare machine.</p>"},{"location":"demo/#genesis-file-handling","title":"Genesis File handling","text":"<p>Assuming you followed our advice and are using a VON Network instance of Hyperledger Indy, you can ignore this section. If you started the Indy ledger without using VON Network, this information might be helpful.</p> <p>An Aries agent (or other client) connecting to an Indy ledger must know the contents of the <code>genesis</code> file for the ledger. The genesis file lets the agent/client know the IP addresses of the initial nodes of the ledger, and the agent/client sends ledger requests to those IP addresses. When using the <code>indy-sdk</code> ledger, look for the instructions in that repo for how to find/update the ledger genesis file, and note the path to that file on your local system.</p> <p>The envrionment variable <code>GENESIS_FILE</code> is used to let the Aries demo agents know the location of the genesis file. Use the path to that file as value of the <code>GENESIS_FILE</code> environment variable in the instructions below. You might want to copy that file to be local to the demo so the path is shorter.</p>"},{"location":"demo/#run-a-local-postgres-instance","title":"Run a local Postgres instance","text":"<p>The demo uses the postgres database the wallet persistence. Use the Docker Hub certified postgres image to start up a postgres instance to be used for the wallet storage:</p> <pre><code>docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres -c 'log_statement=all' -c 'logging_collector=on' -c 'log_destination=stderr'\n</code></pre>"},{"location":"demo/#optional-run-a-von-network-ledger-browser","title":"Optional: Run a von-network ledger browser","text":"<p>If you followed our advice and are using a VON Network instance of Hyperledger Indy, you can ignore this section, as you already have a Ledger browser running, accessible on http://localhost:9000.</p> <p>If you started the Indy ledger without using VON Network, and you want to be able to browse your local ledger as you run the demo, clone the von-network repo, go into the root of the cloned instance and run the following command, replacing the <code>/path/to/local-genesis.txt</code> with a path to the same genesis file as was used in starting the ledger.</p> <pre><code>GENESIS_FILE=/path/to/local-genesis.txt PORT=9000 REGISTER_NEW_DIDS=true python -m server.server\n</code></pre>"},{"location":"demo/#run-the-alice-and-faber-controllersagents","title":"Run the Alice and Faber Controllers/Agents","text":"<p>With the rest of the pieces running, you can run the Alice and Faber controllers and agents. To do so, <code>cd</code> into the <code>demo</code> folder your clone of this repo in two terminal windows.</p> <p>If you are using a VON Network instance of Hyperledger, run the following commands:</p> <pre><code>DEFAULT_POSTGRES=true python3 -m runners.faber --port 8020\n</code></pre> <pre><code>DEFAULT_POSTGRES=true python3 -m runners.alice --port 8030\n</code></pre> <p>If you started the Indy ledger without using VON Network, use the following commands, replacing the <code>/path/to/local-genesis.txt</code> with the one for your configuration.</p> <pre><code>GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners.faber --port 8020\n</code></pre> <pre><code>GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners.alice --port 8030\n</code></pre> <p>Note that Alice and Faber will each use 5 ports, e.g., using the parameter <code>... --port 8020</code> actually uses ports 8020 through 8024. Feel free to use different ports if you want.</p> <p>Everything running?  See the Follow the Script section below for further instructions.</p> <p>If the demo fails with an error that references the genesis file, a timeout connecting to the Indy Pool, or an Indy <code>307</code> error, it's likely a problem with the genesis file handling. Things to check:</p> <ul> <li>Review the instructions for running the ledger with <code>indy-sdk</code>. Is it running properly?</li> <li>Is the <code>/path/to/local-genesis.txt</code> file correct in your start commands?</li> <li>Look at the IP addresses in the genesis file you are using, and make sure that those IP addresses are accessible from the location you are running the Aries demo</li> <li>Check to make sure that all of the nodes of the ledger started. We've seen examples of only some of the nodes starting up, triggering an Indy <code>307</code> error.</li> </ul>"},{"location":"demo/#follow-the-script","title":"Follow The Script","text":"<p>With both the Alice and Faber agents started, go to the Faber terminal window. The Faber agent has created and displayed an invitation. Copy this invitation and paste it at the Alice prompt. The agents will connect and then show a menu of options:</p> <p>Faber:</p> <pre><code>    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (4) Create New Invitation\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n</code></pre> <p>Alice:</p> <pre><code>    (3) Send Message\n    (4) Input New Invitation\n    (X) Exit?\n</code></pre>"},{"location":"demo/#exchanging-messages","title":"Exchanging Messages","text":"<p>Feel free to use the \"3\" option to send messages back and forth between the agents. Fun, eh? Those are secure, end-to-end encrypted messages.</p>"},{"location":"demo/#issuing-and-proving-credentials","title":"Issuing and Proving Credentials","text":"<p>When ready to test the credentials exchange protocols, go to the Faber prompt, enter \"1\" to send a credential, and then \"2\" to request a proof.</p> <p>You don't need to do anything with Alice's agent - her agent is implemented to automatically receive credentials and respond to proof requests.</p> <p>Note there is an option \"2a\" to initiate a connectionless proof - you can execute this option but it will only work end-to-end when connecting to Faber from a mobile agent.</p>"},{"location":"demo/#additional-options-in-the-alicefaber-demo","title":"Additional Options in the Alice/Faber demo","text":"<p>You can enable support for various ACA-Py features by providing additional command-line arguements when starting up <code>alice</code> or <code>faber</code>.</p> <p>Note that when the controller starts up the agent, it prints out the ACA-Py startup command with all parameters - you can inspect this command to see what parameters are provided in each case.  For more details on the parameters, just start ACA-Py with the <code>--help</code> parameter, for example:</p> <pre><code>./scripts/run_docker start --help\n</code></pre>"},{"location":"demo/#revocation","title":"Revocation","text":"<p>To enable support for revoking credentials, run the <code>faber</code> demo with the <code>--revocation</code> option:</p> <pre><code>./run_demo faber --revocation\n</code></pre> <p>Note that you don't specify this option with <code>alice</code> because it's only applicable for the credential <code>issuer</code> (who has to enable revocation when creating a credential definition, and explicitly revoke credentials as appropriate; alice doesn't have to do anything special when revocation is enabled).</p> <p>You need to run an AnonCreds revocation registry tails server in order to support revocation - the details are described in the Alice gets a Phone demo instructions.</p> <p>Faber will setup support for revocation automatically, and you will see an extra option in faber's menu to revoke a credential:</p> <p><pre><code>    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (4) Create New Invitation\n    (5) Revoke Credential\n    (6) Publish Revocations\n    (7) Rotate Revocation Registry\n    (8) List Revocation Registries\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n  ```\n\nWhen you issue a credential, make a note of the `Revocation registry ID` and `Credential revocation ID`:\n</code></pre> Faber      | Revocation registry ID: WGmUNAdH2ZfeGvacFoMVVP:4:WGmUNAdH2ZfeGvacFoMVVP:3:CL:38:Faber.Agent.degree_schema:CL_ACCUM:15ca49ed-1250-4608-9e8f-c0d52d7260c3 Faber      | Credential revocation ID: 1 <pre><code>When you revoke a credential you will need to provide those values:\n</code></pre> [\u00bd/\u00be/\u215a/\u215e/T/X] 5</p> <p>Enter revocation registry ID: WGmUNAdH2ZfeGvacFoMVVP:4:WGmUNAdH2ZfeGvacFoMVVP:3:CL:38:Faber.Agent.degree_schema:CL_ACCUM:15ca49ed-1250-4608-9e8f-c0d52d7260c3 Enter credential revocation ID: 1 Publish now? [Y/N]: y <pre><code>Note that you need to Publish the revocation information to the ledger.  Once you've revoked a credential any proof which uses this credential will fail to verify.  \n\nRotating the revocation registry will decommission any \"ready\" registry records and create 2 new registry records. You can view in the logs as the records are created and transition to 'active'. There should always be 2 'active' revocation registries - one working and one for hot-swap. Note that revocation information can still be published from decommissioned registries.\n\nYou can also list the created registries, filtering by current state: 'init', 'generated', 'posted', 'active', 'full', 'decommissioned'.\n\n### DID Exchange\n\nYou can enable DID Exchange using the `--did-exchange` parameter for the `alice` and `faber` demos.\n\nThis will use the new DID Exchange protocol when establishing connections between the agents, rather than the older Connection protocol.  There is no other affect on the operation of the agents.\n\nNote that you can't (currently) use the DID Exchange protocol to connect with any of the available mobile agents.\n\n### Endorser\n\nThis is described in [Endorser.md](Endorser.md)\n\n### Run Indy-SDK Backend\n\nThis runs using the older (and not recommended) indy-sdk libraries instead of [Aries Askar](https://github.com/hyperledger/aries-ask):\n\n```bash\n./run_demo faber --wallet-type indy\n</code></pre></p>"},{"location":"demo/#mediation","title":"Mediation","text":"<p>To enable mediation, run the <code>alice</code> or <code>faber</code> demo with the <code>--mediation</code> option:</p> <pre><code>./run_demo faber --mediation\n</code></pre> <p>This will start up a \"mediator\" agent with Alice or Faber and automatically set the alice/faber connection to use the mediator.</p>"},{"location":"demo/#multi-ledger","title":"Multi-ledger","text":"<p>To enable multiple ledger mode, run the <code>alice</code> or <code>faber</code> demo with the <code>--multi-ledger</code> option:</p> <pre><code>./run_demo faber --multi-ledger\n</code></pre> <p>The configuration file for setting up multiple ledgers (for the demo) can be found at <code>./demo/multiple_ledger_config.yml</code>.</p>"},{"location":"demo/#multi-tenancy","title":"Multi-tenancy","text":"<p>To enable support for multi-tenancy, run the <code>alice</code> or <code>faber</code> demo with the <code>--multitenant</code> option:</p> <pre><code>./run_demo faber --multitenant\n</code></pre> <p>(This option can be used with both (or either) <code>alice</code> and/or <code>faber</code>.)</p> <p>You will see an additional menu option to create new sub-wallets (or they can be considered to be \"virtual agents\").</p> <p>Faber:</p> <pre><code>    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (4) Create New Invitation\n    (W) Create and/or Enable Wallet\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n</code></pre> <p>Alice:</p> <pre><code>    (3) Send Message\n    (4) Input New Invitation\n    (W) Create and/or Enable Wallet\n    (X) Exit?\n</code></pre> <p>When you create a new wallet, you just need to provide the wallet name. (If you provide the name of an existing wallet then the controller will \"activate\" that wallet and make it the current wallet.)</p> <pre><code>[1/2/3/4/W/T/X] w\n\nEnter wallet name: new_wallet_12\n\nFaber      | Register or switch to wallet new_wallet_12\nFaber      | Created new profile\nFaber      | Profile backend: indy\nFaber      | Profile name: new_wallet_12\nFaber      | No public DID\n... etc\n</code></pre> <p>Note that <code>faber</code> will create a public DID for this wallet, and will create a schema and credential definition.</p> <p>Once you have created a new wallet, you must establish a connection between <code>alice</code> and <code>faber</code> (remember that this is a new \"virtual agent\" and doesn't know anything about connections established for other \"agents\").</p> <p>In faber, create a new invitation:</p> <pre><code>[1/2/3/4/W/T/X] 4\n\n(... creates a new invitation ...)\n</code></pre> <p>In alice, accept the invitation:</p> <pre><code>[1/2/3/4/W/T/X] 4\n\n(... enter the new invitation string ...)\n</code></pre> <p>You can inspect the additional multi-tenancy admin API's (i.e. the \"agency API\" by opening either agent's swagger page in your browser:</p> Show me a screenshot - multi-tenancy via admin API <p>Note that with multi-tenancy enabled:</p> <ul> <li>The \"base\" wallet will have access to this new \"agency API\" - the agent's admin key, if enabled, must be provided in a header</li> <li>\"Base wallet\" API calls are handled here</li> <li>The \"sub-wallets\" will have access to the \"normal\" ACA-Py admin API - to identify the sub-wallet, a JWT token must be provided, this token is created upon creation of the new wallet (see: this code here)</li> <li>\"Sub-wallet\" API calls are handled here</li> </ul> <p>Documentation on ACA-Py's multi-tenancy support can be found here.</p>"},{"location":"demo/#multi-tenancy-with-mediation","title":"Multi-tenancy with Mediation!!!","text":"<p>There are two options for configuring mediation with multi-tenancy, documented here.</p> <p>This demo implements option #2 - each sub-wallet is configured with a separate connection to the mediator.</p> <p>Run the demo (Alice or Faber) specifying both options:</p> <pre><code>./run_demo faber --multitenant --mediation\n</code></pre> <p>This works exactly as the vanilla multi-tenancy, except that all connections are mediated.</p>"},{"location":"demo/#other-environment-settings","title":"Other Environment Settings","text":"<p>The agents run on a pre-defined set of ports, however occasionally your local system may already be using one of these ports.  (For example MacOS recently decided to use 8021 for the ftp proxy service.)</p> <p>To overriide the default port settings:</p> <pre><code>AGENT_PORT_OVERRIDE=8010 ./run_demo faber\n</code></pre> <p>(The agent requires up to 10 available ports.)</p> <p>To pass extra arguements to the agent (for example):</p> <pre><code>DEMO_EXTRA_AGENT_ARGS=\"[\\\"--emit-did-peer-2\\\"]\" ./run_demo faber --did-exchange --reuse-connections\n</code></pre>"},{"location":"demo/#learning-about-the-alicefaber-code","title":"Learning about the Alice/Faber code","text":"<p>These Alice and Faber scripts (in the <code>demo/runners</code> folder) implement the controller and run the agent as a sub-process (see the documentation for <code>aca-py</code>). The controller publishes a REST service to receive web hook callbacks from their agent. Note that this architecture, running the agent as a sub-process, is a variation on the documented architecture of running the controller and agent as separate processes/containers.</p> <p>The controllers for this demo can be found in the alice.py and faber.py files. Alice and Faber are instances of the agent class found in agent.py.</p>"},{"location":"demo/#openapi-swagger-demo","title":"OpenAPI (Swagger) Demo","text":"<p>Developing an ACA-Py controller is much like developing a web app that uses a REST API. As you develop, you will want an easy way to test out the behaviour of the API. That's where the industry-standard OpenAPI (aka Swagger) UI comes in. ACA-Py (optionally) exposes an OpenAPI UI in ACA-Py that you can use to learn the ins and outs of the API. This Aries OpenAPI demo shows how you can use the OpenAPI UI with an ACA-Py agent by walking through the connectiing, issuing a credential, and presenting a proof sequence.</p>"},{"location":"demo/#performance-demo","title":"Performance Demo","text":"<p>Another example in the <code>demo/runners</code> folder is performance.py, that is used to test out the performance of interacting agents. The script starts up agents for Alice and Faber, initializes them, and then runs through an interaction some number of times. In this case, Faber issues a credential to Alice 300 times.</p> <p>To run the demo, make sure that you shut down any running Alice/Faber agents. Then, follow the same steps to start the Alice/Faber demo, but:</p> <ul> <li>When starting the first agent, replace the agent name (e.g. <code>faber</code>) with <code>performance</code>.</li> <li>Don't start the second agent (<code>alice</code>) at all.</li> </ul> <p>The script starts both agents, runs the performance test, spits out performance results and shuts down the agents. Note that this is just one demonstration of how performance metrics tracking can be done with ACA-Py.</p> <p>A second version of the performance test can be run by adding the parameter <code>--routing</code> to the invocation above. The parameter triggers the example to run with Alice using a routing agent such that all messages pass through the routing agent between Alice and Faber. This is a good, simple example of how routing can be implemented with DIDComm agents.</p> <p>You can also run the demo against a postgres database using the following:</p> <pre><code>./run_demo performance --arg-file demo/postgres-indy-args.yml\n</code></pre> <p>(Obvs you need to be running a postgres database - the command to start postgres is in the yml file provided above.)</p> <p>You can tweak the number of credentials issued using the <code>--count</code> and <code>--batch</code> parameters, and you can run against an Askar database using the <code>--wallet-type askar</code> option (or run using indy-sdk using <code>--wallet-type indy</code>).</p> <p>An example full set of options is:</p> <pre><code>./run_demo performance --arg-file demo/postgres-indy-args.yml -c 10000 -b 10 --wallet-type askar\n</code></pre> <p>Or:</p> <pre><code>./run_demo performance --arg-file demo/postgres-indy-args.yml -c 10000 -b 10 --wallet-type indy\n</code></pre>"},{"location":"demo/#coding-challenge-adding-acme","title":"Coding Challenge: Adding ACME","text":"<p>Now that you have a solid foundation in using ACA-Py, time for a coding challenge. In this challenge, we extend the Alice-Faber command line demo by adding in ACME Corp, a place where Alice wants to work. The demo adds:</p> <ul> <li>ACME inviting Alice to connect</li> <li>ACME requesting a proof of her College degree</li> <li>ACME issuing Alice a credential after she is hired.</li> </ul> <p>The framework for the code is in the acme.py file, but the code is incomplete. Using the knowledge you gained from running demo and viewing the alice.py and faber.py code, fill in the blanks for the code.  When you are ready to test your work:</p> <ul> <li>Use the instructions above to start the Alice/Faber demo (above).</li> <li>Start another terminal session and run the same commands as for \"Alice\", but replace \"alice\" with \"acme\".</li> </ul> <p>All done? Checkout how we added the missing code segments here.</p>"},{"location":"demo/AcmeDemoWorkshop/","title":"Acme Controller Workshop","text":"<p>In this workshop we will add some functionality to a third participant in the Alice/Faber drama - namely, Acme Inc.  After completing her education at Faber College, Alice is going to apply for a job at Acme Inc.  To do this she must provide proof of education (once she has completed the interview and other non-Indy tasks), and then Acme will issue her an employment credential.</p> <p>Note that an updated Acme controller is available here: https://github.com/ianco/aries-cloudagent-python/tree/acme_workshop/demo if you just want to skip ahead ...  There is also an alternate solution with some additional functionality available here:  https://github.com/ianco/aries-cloudagent-python/tree/agent_workshop/demo</p>"},{"location":"demo/AcmeDemoWorkshop/#preview-of-the-acme-controller","title":"Preview of the Acme Controller","text":"<p>There is already a skeleton of the Acme controller in place, you can run it as follows.  (Note that beyond establishing a connection it doesn't actually do anything yet.)</p> <p>To run the Acme controller template, first run Alice and Faber so that Alice can prove her education experience:</p> <p>Open 2 bash shells, and in each run:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>In one shell run Faber:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber\n</code></pre> <p>... and in the second shell run Alice:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice\n</code></pre> <p>When Faber has produced an invitation, copy it over to Alice.</p> <p>Then, in the Faber shell, select option <code>1</code> to issue a credential to Alice.  (You can select option <code>2</code> if you like, to confirm via proof.)</p> <p>Then, in the Faber shell, enter <code>X</code> to exit the controller, and then run the Acme controller:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo acme\n</code></pre> <p>In the Alice shell, select option <code>4</code> (to enter a new invitation) and then copy over Acme's invitation once it's available.</p> <p>Then, in the Acme shell, you can select option <code>2</code> and then option <code>1</code>, which don't do anything ... yet!!!</p>"},{"location":"demo/AcmeDemoWorkshop/#asking-alice-for-a-proof-of-education","title":"Asking Alice for a Proof of Education","text":"<p>In the Acme code <code>acme.py</code> we are going to add code to issue a proof request to Alice, and then validate the received proof.</p> <p>First the following import statements and constants that we will need near the top of acme.py:</p> <pre><code>import random\n\nfrom datetime import date\nfrom uuid import uuid4\n</code></pre> <pre><code>TAILS_FILE_COUNT = int(os.getenv(\"TAILS_FILE_COUNT\", 100))\nCRED_PREVIEW_TYPE = \"https://didcomm.org/issue-credential/2.0/credential-preview\"\n</code></pre> <p>Next locate the code that is triggered by option <code>2</code>:</p> <pre><code>            elif option == \"2\":\n                log_status(\"#20 Request proof of degree from alice\")\n                # TODO presentation requests\n</code></pre> <p>Replace the <code># TODO</code> comment with the following code:</p> <pre><code>                req_attrs = [\n                    {\n                        \"name\": \"name\",\n                        \"restrictions\": [{\"schema_name\": \"degree schema\"}]\n                    },\n                    {\n                        \"name\": \"date\",\n                        \"restrictions\": [{\"schema_name\": \"degree schema\"}]\n                    },\n                    {\n                        \"name\": \"degree\",\n                        \"restrictions\": [{\"schema_name\": \"degree schema\"}]\n                    }\n                ]\n                req_preds = []\n                indy_proof_request = {\n                    \"name\": \"Proof of Education\",\n                    \"version\": \"1.0\",\n                    \"nonce\": str(uuid4().int),\n                    \"requested_attributes\": {\n                        f\"0_{req_attr['name']}_uuid\": req_attr\n                        for req_attr in req_attrs\n                    },\n                    \"requested_predicates\": {}\n                }\n                proof_request_web_request = {\n                    \"connection_id\": agent.connection_id,\n                    \"presentation_request\": {\"indy\": indy_proof_request},\n                }\n                # this sends the request to our agent, which forwards it to Alice\n                # (based on the connection_id)\n                await agent.admin_POST(\n                    \"/present-proof-2.0/send-request\",\n                    proof_request_web_request\n                )\n</code></pre> <p>Now we need to handle receipt of the proof.  Locate the code that handles received proofs (this is in a webhook callback):</p> <pre><code>        if state == \"presentation-received\":\n            # TODO handle received presentations\n            pass\n</code></pre> <p>then replace the <code># TODO</code> comment and the <code>pass</code> statement:</p> <pre><code>            log_status(\"#27 Process the proof provided by X\")\n            log_status(\"#28 Check if proof is valid\")\n            proof = await self.admin_POST(\n                f\"/present-proof-2.0/records/{pres_ex_id}/verify-presentation\"\n            )\n            self.log(\"Proof = \", proof[\"verified\"])\n\n            # if presentation is a degree schema (proof of education),\n            # check values received\n            pres_req = message[\"by_format\"][\"pres_request\"][\"indy\"]\n            pres = message[\"by_format\"][\"pres\"][\"indy\"]\n            is_proof_of_education = (\n                pres_req[\"name\"] == \"Proof of Education\"\n            )\n            if is_proof_of_education:\n                log_status(\"#28.1 Received proof of education, check claims\")\n                for (referent, attr_spec) in pres_req[\"requested_attributes\"].items():\n                    if referent in pres['requested_proof']['revealed_attrs']:\n                        self.log(\n                            f\"{attr_spec['name']}: \"\n                            f\"{pres['requested_proof']['revealed_attrs'][referent]['raw']}\"\n                        )\n                    else:\n                        self.log(\n                            f\"{attr_spec['name']}: \"\n                            \"(attribute not revealed)\"\n                        )\n                for id_spec in pres[\"identifiers\"]:\n                    # just print out the schema/cred def id's of presented claims\n                    self.log(f\"schema_id: {id_spec['schema_id']}\")\n                    self.log(f\"cred_def_id {id_spec['cred_def_id']}\")\n                # TODO placeholder for the next step\n            else:\n                # in case there are any other kinds of proofs received\n                self.log(\"#28.1 Received \", pres_req[\"name\"])\n</code></pre> <p>Right now this just verifies the proof received and prints out the attributes it reveals, but in \"real life\" your application could do something useful with this information.</p> <p>Now you can run the Faber/Alice/Acme script from the \"Preview of the Acme Controller\" section above, and you should see Acme receive a proof from Alice!</p>"},{"location":"demo/AcmeDemoWorkshop/#issuing-alice-a-work-credential","title":"Issuing Alice a Work Credential","text":"<p>Now we can issue a work credential to Alice!</p> <p>There are two options for this.  We can (a) add code under option <code>1</code> to issue the credential, or (b) we can automatically issue this credential on receipt of the education proof.</p> <p>We're going to do option (a), but you can try to implement option (b) as homework.  You have most of the information you need from the proof response!</p> <p>First though we need to register a schema and credential definition.  Find this code:</p> <pre><code>        # acme_schema_name = \"employee id schema\"\n        # acme_schema_attrs = [\"employee_id\", \"name\", \"date\", \"position\"]\n        await acme_agent.initialize(\n            the_agent=agent,\n            # schema_name=acme_schema_name,\n            # schema_attrs=acme_schema_attrs,\n        )\n\n        # TODO publish schema and cred def\n</code></pre> <p>... and uncomment the code lines. Replace the <code># TODO</code> comment with the following code:</p> <pre><code>        with log_timer(\"Publish schema and cred def duration:\"):\n            # define schema\n            version = format(\n                \"%d.%d.%d\"\n                % (\n                    random.randint(1, 101),\n                    random.randint(1, 101),\n                    random.randint(1, 101),\n                )\n            )\n            # register schema and cred def\n            (schema_id, cred_def_id) = await agent.register_schema_and_creddef(\n                \"employee id schema\",\n                version,\n                [\"employee_id\", \"name\", \"date\", \"position\"],\n                support_revocation=False,\n                revocation_registry_size=TAILS_FILE_COUNT,\n            )\n</code></pre> <p>For option (1) we want to replace the <code># TODO</code> comment here:</p> <pre><code>            elif option == \"1\":\n                log_status(\"#13 Issue credential offer to X\")\n                # TODO credential offers\n</code></pre> <p>with the following code:</p> <pre><code>                agent.cred_attrs[cred_def_id] = {\n                    \"employee_id\": \"ACME0009\",\n                    \"name\": \"Alice Smith\",\n                    \"date\": date.isoformat(date.today()),\n                    \"position\": \"CEO\"\n                }\n                cred_preview = {\n                    \"@type\": CRED_PREVIEW_TYPE,\n                    \"attributes\": [\n                        {\"name\": n, \"value\": v}\n                        for (n, v) in agent.cred_attrs[cred_def_id].items()\n                    ],\n                }\n                offer_request = {\n                    \"connection_id\": agent.connection_id,\n                    \"comment\": f\"Offer on cred def id {cred_def_id}\",\n                    \"credential_preview\": cred_preview,\n                    \"filter\": {\"indy\": {\"cred_def_id\": cred_def_id}},\n                }\n                await agent.admin_POST(\n                    \"/issue-credential-2.0/send-offer\", offer_request\n                )\n</code></pre> <p>... and then locate the code that handles the credential request callback:</p> <pre><code>        if state == \"request-received\":\n            # TODO issue credentials based on offer preview in cred ex record\n            pass\n</code></pre> <p>... and replace the <code># TODO</code> comment and <code>pass</code> statement with the following code to issue the credential as Acme offered it:</p> <pre><code>            # issue credentials based on offer preview in cred ex record\n            if not message.get(\"auto_issue\"):\n                await self.admin_POST(\n                    f\"/issue-credential-2.0/records/{cred_ex_id}/issue\",\n                    {\"comment\": f\"Issuing credential, exchange {cred_ex_id}\"},\n                )\n</code></pre> <p>Now you can run the Faber/Alice/Acme steps again.  You should be able to receive a proof and then issue a credential to Alice.</p>"},{"location":"demo/AliceGetsAPhone/","title":"Alice Gets a Mobile Agent!","text":"<p>In this demo, we'll again use our familiar Faber ACA-Py agent to issue credentials to Alice, but this time Alice will use a mobile wallet. To do this we need to run the Faber agent on a publicly accessible port, and Alice will need a compatible mobile wallet. We'll provide pointers to where you can get them.</p> <p>This demo also introduces revocation of credentials.</p>"},{"location":"demo/AliceGetsAPhone/#contents","title":"Contents","text":"<ul> <li>Getting Started</li> <li>Get a mobile agent</li> <li>Running Locally in Docker<ul> <li>Install ngrok and jq</li> <li>Expose services publicly using ngrok</li> </ul> </li> <li>Running in Play With Docker</li> <li>Run an instance of indy-tails-server<ul> <li>Running locally in a bash shell?</li> <li>Running in Play with Docker?</li> </ul> </li> <li>Run <code>faber</code> With Extra Parameters<ul> <li>Running locally in a bash shell?</li> <li>Running in Play with Docker?</li> <li>Waiting for the Faber agent to start ...</li> </ul> </li> <li>Accept the Invitation</li> <li>Issue a Credential</li> <li>Accept the Credential</li> <li>Issue a Presentation Request</li> <li>Present the Proof</li> <li>Review the Proof</li> <li>Revoke the Credential and Send Another Proof Request</li> <li>Send a Connectionless Proof Request</li> <li>Conclusion</li> </ul>"},{"location":"demo/AliceGetsAPhone/#getting-started","title":"Getting Started","text":"<p>This demo can be run on your local machine or on Play with Docker (PWD), and will demonstrate credential exchange and proof exchange as well as revocation with a mobile agent. Both approaches (running locally and on PWD) will be described, for the most part the commands are the same, but there are a couple of different parameters you need to provide when starting up.</p> <p>If you are not familiar with how revocation is currently implemented in Hyperledger Indy, this article provides a good background on the technique. A challenge with revocation as it is currently implemented in Hyperledger Indy is the need for the prover (the agent creating the proof) to download tails files associated with the credentials it holds.</p>"},{"location":"demo/AliceGetsAPhone/#get-a-mobile-agent","title":"Get a mobile agent","text":"<p>Of course for this, you need to have a mobile agent. To find, install and setup a compatible mobile agent, follow the instructions here.</p>"},{"location":"demo/AliceGetsAPhone/#running-locally-in-docker","title":"Running Locally in Docker","text":"<p>Open a new bash shell and in a project directory run the following:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>We'll come back to this in a minute, when we start the <code>faber</code> agent!</p> <p>There are a couple of extra steps you need to take to prepare to run the Faber agent locally:</p>"},{"location":"demo/AliceGetsAPhone/#install-ngrok-and-jq","title":"Install ngrok and jq","text":"<p>ngrok is used to expose public endpoints for services running locally on your computer.</p> <p>jq is a json parser that is used to automatically detect the endpoints exposed by ngrok.</p> <p>You can install ngrok from here</p> <p>You can download jq releases here</p>"},{"location":"demo/AliceGetsAPhone/#expose-services-publicly-using-ngrok","title":"Expose services publicly using ngrok","text":"<p>Note that this is only required when running docker on your local machine. When you run on PWD a public endpoint for your agent is exposed automatically.</p> <p>Since the mobile agent will need some way to communicate with the agent running on your local machine in docker, we will need to create a publicly accesible url for some services on your machine. The easiest way to do this is with ngrok. Once ngrok is installed, create a tunnel to your local machine:</p> <pre><code>ngrok http 8020\n</code></pre> <p>This service is used for your local aca-py agent - it is the endpoint that is advertised for other Aries agents to connect to.</p> <p>You will see something like this:</p> <pre><code>Forwarding                    http://abc123.ngrok.io -&gt; http://localhost:8020\nForwarding                    https://abc123.ngrok.io -&gt; http://localhost:8020\n</code></pre> <p>This creates a public url for ports 8020 on your local machine.</p> <p>Note that an ngrok process is created automatically for your tails server.</p> <p>Keep this process running as we'll come back to it in a moment.</p>"},{"location":"demo/AliceGetsAPhone/#running-in-play-with-docker","title":"Running in Play With Docker","text":"<p>To run the necessary terminal sessions in your browser, go to the Docker playground service Play with Docker. Don't know about Play with Docker? Check this out to learn more.</p> <p>Open a new bash shell and in a project directory run the following:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>We'll come back to this in a minute, when we start the <code>faber</code> agent!</p>"},{"location":"demo/AliceGetsAPhone/#run-an-instance-of-indy-tails-server","title":"Run an instance of indy-tails-server","text":"<p>For revocation to function, we need another component running that is used to store what are called tails files.</p> <p>If you are not running with revocation enabled you can skip this step.</p>"},{"location":"demo/AliceGetsAPhone/#running-locally-in-a-bash-shell","title":"Running locally in a bash shell?","text":"<p>Open a new bash shell, and in a project directory, run:</p> <pre><code>git clone https://github.com/bcgov/indy-tails-server.git\ncd indy-tails-server/docker\n./manage build\n./manage start\n</code></pre> <p>This will run the required components for the tails server to function and make a tails server available on port 6543.</p> <p>This will also automatically start an ngrok server that will expose a public url for your tails server - this is required to support mobile agents. The docker output will look something like this:</p> <pre><code>ngrok-tails-server_1  | t=2020-05-13T22:51:14+0000 lvl=info msg=\"started tunnel\" obj=tunnels name=\"command_line (http)\" addr=http://tails-server:6543 url=http://c5789aa0.ngrok.io\nngrok-tails-server_1  | t=2020-05-13T22:51:14+0000 lvl=info msg=\"started tunnel\" obj=tunnels name=command_line addr=http://tails-server:6543 url=https://c5789aa0.ngrok.io\n</code></pre> <p>Note the server name in the <code>url=https://c5789aa0.ngrok.io</code> parameter (<code>https://c5789aa0.ngrok.io</code>) - this is the external url for your tails server. Make sure you use the <code>https</code> url!</p>"},{"location":"demo/AliceGetsAPhone/#running-in-play-with-docker_1","title":"Running in Play with Docker?","text":"<p>Run the same steps on PWD as you would run locally (see above).  Open a new shell (click on \"ADD NEW INSTANCE\") to run the tails server.</p> <p>Note that with Play with Docker it can be challenging to capture the information you need from the log file as it scrolls by, you can try leaving off the <code>--events</code> option when you run the Faber agent to reduce the quantity of information logged to the screen.</p>"},{"location":"demo/AliceGetsAPhone/#run-faber-with-extra-parameters","title":"Run <code>faber</code> With Extra Parameters","text":""},{"location":"demo/AliceGetsAPhone/#running-locally-in-a-bash-shell_1","title":"Running locally in a bash shell?","text":"<p>If you are running in a local bash shell, navigate to the <code>demo</code> directory in your fork/clone of the Aries Cloud Agent Python repository and run:</p> <pre><code>TAILS_NETWORK=docker_tails-server LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --aip 10 --revocation --events\n</code></pre> <p>(Note that we have to start faber with <code>--aip 10</code> for compatibility with mobile clients.)</p> <p>The <code>TAILS_NETWORK</code> parameter lets the demo script know how to connect to the tails server (which should be running in a separate shell on the same machine).</p>"},{"location":"demo/AliceGetsAPhone/#running-in-play-with-docker_2","title":"Running in Play with Docker?","text":"<p>If you are running in Play with Docker, navigate to the <code>demo</code> folder in the clone of Aries Cloud Agent Python and run the following:</p> <pre><code>PUBLIC_TAILS_URL=https://c4f7fbb85911.ngrok.io LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --aip 10 --revocation --events\n</code></pre> <p>The <code>PUBLIC_TAILS_URL</code> parameter lets the demo script know how to connect to the tails server. This can be running in another PWD session, or even on your local machine - the ngrok endpoint is public and will map to the correct location.</p> <p>Use the ngrok url for the tails server that you noted earlier.</p> <p>*Note that you must use the <code>https</code> url for the tails server endpoint.</p> <p>*Note - you may want to leave off the <code>--events</code> option when you run the Faber agent, if you are finding you are getting too much logging output.</p>"},{"location":"demo/AliceGetsAPhone/#waiting-for-the-faber-agent-to-start","title":"Waiting for the Faber agent to start ...","text":"<p>The <code>Preparing agent image...</code> step on the first run takes a bit of time, so while we wait, let's look at the details of the commands. Running Faber is similar to the instructions in the Aries OpenAPI Demo \"Play with Docker\" section, except:</p> <ul> <li>We are using the BCovrin Test network because that is a network that the mobile agents can be configured to use.</li> <li>We are running in \"auto\" mode, so we will make no manual acknowledgements.</li> <li>The revocation related changes:</li> <li>The <code>TAILS_NETWORK</code> parameter tells the <code>./run_demo</code> script how to connect to the tails server and determine the public ngrok endpoint.</li> <li>The <code>PUBLIC_TAILS_URL</code> environment variable is the address of your tails server (must be <code>https</code>).</li> <li>The <code>--revocation</code> parameter to the <code>./run-demo</code> script activates the ACA-Py revocation issuance.</li> </ul> <p>As part of its startup process, the agent will publish a revocation registry to the ledger.</p> Click here to view screenshot of the revocation registry on the ledger"},{"location":"demo/AliceGetsAPhone/#accept-the-invitation","title":"Accept the Invitation","text":"<p>When the Faber agent starts up it automatically creates an invitation and generates a QR code on the screen. On your mobile app, select \"SCAN CODE\" (or equivalent) and point your camera at the generated QR code. The mobile agent should automatically capture the code and ask you to confirm the connection. Confirm it.</p> Click here to view screenshot <p>The mobile agent will give you feedback on the connection process, something like \"A connection was added to your wallet\".</p> Click here to view screenshot Click here to view screenshot <p>Switch your browser back to Play with Docker. You should see that the connection has been established, and there is a prompt for what actions you want to take, e.g. \"Issue Credential\", \"Send Proof Request\" and so on.</p> <p>Tip: If your screen is too small to display the QR code (this can happen in Play With Docker because the shell is only given a small portion of the browser) you can copy the invitation url to a site like https://www.the-qrcode-generator.com/ to convert the invitation url into a QR code that you can scan. Make sure you select the <code>URL</code> option, and copy the <code>invitation_url</code>, which will look something like:</p> <pre><code>https://abfde260.ngrok.io?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiZjI2ZjA2YTItNWU1Mi00YTA5LWEwMDctOTNkODBiZTYyNGJlIiwgInJlY2lwaWVudEtleXMiOiBbIjlQRFE2alNXMWZwZkM5UllRWGhCc3ZBaVJrQmVKRlVhVmI0QnRQSFdWbTFXIl0sICJsYWJlbCI6ICJGYWJlci5BZ2VudCIsICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9hYmZkZTI2MC5uZ3Jvay5pbyJ9\n</code></pre> <p>Or this:</p> <pre><code>http://ip10-0-121-4-bquqo816b480a4bfn3kg-8020.direct.play-with-docker.com?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiZWI2MTI4NDUtYmU1OC00YTNiLTk2MGUtZmE3NDUzMGEwNzkyIiwgInJlY2lwaWVudEtleXMiOiBbIkFacEdoMlpIOTJVNnRFRTlmYk13Z3BqQkp3TEUzRFJIY1dCbmg4Y2FqdzNiIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cDovL2lwMTAtMC0xMjEtNC1icXVxbzgxNmI0ODBhNGJmbjNrZy04MDIwLmRpcmVjdC5wbGF5LXdpdGgtdm9uLnZvbnguaW8iLCAibGFiZWwiOiAiRmFiZXIuQWdlbnQifQ==\n</code></pre> <p>Note that this will use the ngrok endpoint if you are running locally, or your PWD endpoint if you are running on PWD.</p>"},{"location":"demo/AliceGetsAPhone/#issue-a-credential","title":"Issue a Credential","text":"<p>We will use the Faber console to issue a credential. This could be done using the Swagger API as we have done in the connection process. We'll leave that as an exercise to the user.</p> <p>In the Faber console, select option <code>1</code> to send a credential to the mobile agent.</p> Click here to view screenshot <p>The Faber agent outputs details to the console; e.g.,</p> <pre><code>Faber      | Credential: state = credential-issued, cred_ex_id = ba3089d6-92da-4cb7-9062-7f24066b2a2a\nFaber      | Revocation registry ID: CMqNjZ8e59jDuBYcquce4D:4:CMqNjZ8e59jDuBYcquce4D:3:CL:50:faber.agent.degree_schema:CL_ACCUM:4f4fb2e4-3a59-45b1-8921-578d005a7ff6\nFaber      | Credential revocation ID: 1\nFaber      | Credential: state = done, cred_ex_id = ba3089d6-92da-4cb7-9062-7f24066b2a2a\n</code></pre> <p>The revocation registry id and credential revocation id only appear if revocation is active. If you are doing revocation, you to need the <code>Revocation registry id</code> later, so we recommend that you copy it it now and paste it into a text file or someplace that you can access later. If you don't write it down, you can get the Id from the Admin API using the <code>GET /revocation/active-registry/{cred_def_id}</code> endpoint, and passing in the credential definition Id (which you can get from the <code>GET /credential-definitions/created</code> endpoint).</p>"},{"location":"demo/AliceGetsAPhone/#accept-the-credential","title":"Accept the Credential","text":"<p>The credential offer should automatically show up in the mobile agent. Accept the offered credential following the instructions provided by the mobile agent. That will look something like this:</p> Click here to view screenshot Click here to view screenshot Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#issue-a-presentation-request","title":"Issue a Presentation Request","text":"<p>We will use the Faber console to ask mobile agent for a proof. This could be done using the Swagger API, but we'll leave that as an exercise to the user.</p> <p>In the Faber console, select option <code>2</code> to send a proof request to the mobile agent.</p> Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#present-the-proof","title":"Present the Proof","text":"<p>The presentation (proof) request should automatically show up in the mobile agent. Follow the instructions provided by the mobile agent to prepare and send the proof back to Faber. That will look something like this:</p> Click here to view screenshot Click here to view screenshot Click here to view screenshot <p>If the mobile agent is able to successfully prepare and send the proof, you can go back to the Play with Docker terminal to see the status of the proof.</p> <p>The process should \"just work\" for the non-revocation use case. If you are using revocation, your results may vary. As of writing this, we get failures on the wallet side with some mobile wallets, and on the Faber side with others (an error in the Indy SDK). As the results improve, we'll update this. Please let us know through GitHub issues if you have any problems running this.</p>"},{"location":"demo/AliceGetsAPhone/#review-the-proof","title":"Review the Proof","text":"<p>In the Faber console window, the proof should be received as validated.</p> Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#revoke-the-credential-and-send-another-proof-request","title":"Revoke the Credential and Send Another Proof Request","text":"<p>If you have enabled revocation, you can try revoking the credential and publishing its pending revoked status (<code>faber</code> options <code>5</code> and <code>6</code>). For the revocation step, You will need the revocation registry identifier and the credential revocation identifier (which is 1 for the first credential you issued), as the Faber agent logged them to the console at credential issue.</p> <p>Once that is done, try sending another proof request and see what happens! Experiment with immediate and pending publication. Note that immediate publication also publishes any pending revocations on its revocation registry.</p> Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#send-a-connectionless-proof-request","title":"Send a Connectionless Proof Request","text":"<p>A connectionless proof request works the same way as a regular proof request, however it does not require a connection to be established between the Verifier and Holder/Prover.</p> <p>This is supported in the Faber demo, however note that it will only work when running Faber on the Docker playground service Play with Docker.  (This is because both the Faber agent and controller both need to be exposed to the mobile agent.)</p> <p>If you have gone through the above steps, you can delete the Faber connection in your mobile agent (however do not delete the credential that Faber issued to you).</p> <p>Then in the faber demo, select option <code>2a</code> - Faber will display a QR code which you can scan with your mobile agent.  You will see the same proof request displayed in your mobile agent, which you can respond to.</p> <p>Behind the scenes, the Faber controller delivers the proof request information (linked from the url encoded in the QR code) directly to your mobile agent, without establishing and agent-to-agent connection first.  If you are interested in the underlying mechanics, you can review the <code>faber.py</code> code in the repository.</p>"},{"location":"demo/AliceGetsAPhone/#conclusion","title":"Conclusion","text":"<p>That\u2019s the Faber-Mobile Alice demo. Feel free to play with the Swagger API and experiment further and figure out what an instance of a controller has to do to make things work.</p>"},{"location":"demo/AliceWantsAJsonCredential/","title":"How to Issue JSON-LD Credentials using ACA-Py","text":"<p>ACA-Py has the capability to issue and verify both Indy and JSON-LD (W3C compliant) credentials.</p> <p>The JSON-LD support is documented here - this document will provide some additional detail in how to use the demo and admin api to issue and prove JSON-LD credentials.</p>"},{"location":"demo/AliceWantsAJsonCredential/#setup-agents-to-issue-json-ld-credentials","title":"Setup Agents to Issue JSON-LD Credentials","text":"<p>Clone this repository to a directory on your local:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>Open up a second shell (so you have 2 shells open in the <code>demo</code> directory) and in one shell:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --did-exchange --aip 20 --cred-type json-ld\n</code></pre> <p>... and in the other:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice\n</code></pre> <p>Note that you start the <code>faber</code> agent with AIP2.0 options.  (When you specify <code>--cred-type json-ld</code> faber will set aip to <code>20</code> automatically, so the <code>--aip</code> option is not strictly required). Note as well the use of the <code>LEDGER_URL</code>. Technically, that should not be needed if we aren't doing anything with an Indy ledger-based credentials. However, there must be something in the way that the Faber and Alice controllers are starting up that requires access to a ledger.</p> <p>Also note that the above will only work with the <code>/issue-credential-2.0/create-offer</code> endpoint.  If you want to use the <code>/issue-credential-2.0/send</code> endpoint - which automates each step of the credential exchange - you will need to include the <code>--no-auto</code> option when starting each of the alice and faber agents (since the alice and faber controllers also automatically respond to each step in the credential exchange).</p> <p>(Alternately you can run run Alice and Faber agents locally, see the <code>./faber-local.sh</code> and <code>./alice-local.sh</code> scripts in the <code>demo</code> directory.)</p> <p>Copy the \"invitation\" json text from the Faber shell and paste into the Alice shell to establish a connection between the two agents.</p> <p>(If you are running with <code>--no-auto</code> you will also need to call the <code>/connections/{conn_id}/accept-invitation</code> endpoint in alice's admin api swagger page.)</p> <p>Now open up two browser windows to the Faber and Alice admin api swagger pages.</p> <p>Using the Faber admin api, you have to create a DID with the appropriate:</p> <ul> <li>DID method (\"key\" or \"sov\")</li> <li>key type \"ed25519\" or \"bls12381g2\" (corresponding to signature types \"Ed25519Signature2018\" or \"BbsBlsSignature2020\")</li> <li>if you use DID method \"sov\" you must use key type \"ed25519\"</li> </ul> <p>Note that \"did:sov\" must be a public DID (i.e. registered on the ledger) but \"did:key\" is not.</p> <p>For example, in Faber's swagger page call the <code>/wallet/did/create</code> endpoint with the following payload:</p> <pre><code>{\n  \"method\": \"key\",\n  \"options\": {\n    \"key_type\": \"bls12381g2\" // or ed25519\n  }\n}\n</code></pre> <p>This will return something like:</p> <pre><code>{\n  \"result\": {\n    \"did\": \"did:key:zUC71KdwBhq1FioWh53VXmyFiGpewNcg8Ld42WrSChpMzzskRWwHZfG9TJ7hPj8wzmKNrek3rW4ZkXNiHAjVchSmTr9aNUQaArK3KSkTySzjEM73FuDV62bjdAHF7EMnZ27poCE\",\n    \"verkey\": \"mV6482Amu6wJH8NeMqH3QyTjh6JU6N58A8GcirMZG7Wx1uyerzrzerA2EjnhUTmjiSLAp6CkNdpkLJ1NTS73dtcra8WUDDBZ3o455EMrkPyAtzst16RdTMsGe3ctyTxxJav\",\n    \"posture\": \"wallet_only\",\n    \"key_type\": \"bls12381g2\",\n    \"method\": \"key\"\n  }\n}\n</code></pre> <p>You do not create a schema or cred def for a JSON-LD credential (these are only required for \"indy\" credentials).</p> <p>You will need to create a DID as above for Alice as well (<code>/wallet/did/create</code> etc ...).</p> <p>Congratulations, you are now ready to start issuing JSON-LD credentials!</p> <ul> <li>You have two agents with a connection established between the agents - you will need to copy Faber's <code>connection_id</code> into the examples below.</li> <li>You have created a (non-public) DID for Faber to use to sign/issue the credentials - you will need to copy the DID that you created above into the examples below (as <code>issuer</code>).</li> <li>You have created a (non-public) DID for Alice to use as her <code>credentialSubject.id</code> - this is required for Alice to sign the proof (the <code>credentialSubject.id</code> is not required, but then the provided presentation can't be verified).</li> </ul> <p>To issue a credential, use the <code>/issue-credential-2.0/send-offer</code> endpoint. (You can also use the <code>/issue-credential-2.0/send</code>) endpoint, if, as mentioned above, you have included the <code>--no-auto</code> when starting both of the agents.)</p> <p>You can test with this example payload (just replace the \"connection_id\", \"issuer\" key, \"credentialSubject.id\" and \"proofType\" with appropriate values:</p> <pre><code>{\n  \"connection_id\": \"4fba2ce5-b411-4ecf-aa1b-ec66f3f6c903\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"UniversityDegreeCredential\"],\n        \"issuer\": \"did:key:zUC71KdwBhq1FioWh53VXmyFiGpewNcg8Ld42WrSChpMzzskRWwHZfG9TJ7hPj8wzmKNrek3rW4ZkXNiHAjVchSmTr9aNUQaArK3KSkTySzjEM73FuDV62bjdAHF7EMnZ27poCE\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"givenName\": \"Sally\",\n          \"familyName\": \"Student\",\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"degreeType\": \"Undergraduate\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre> <p>Note that if you have the \"auto\" settings on, this is all you need to do.  Otherwise you need to call the <code>/send-request</code>, <code>/store</code>, etc endpoints to complete the protocol.</p> <p>To see the issued credential, call the <code>/credentials/w3c</code> endpoint on Alice's admin api - this will return something like:</p> <pre><code>{\n  \"results\": [\n    {\n      \"contexts\": [\n        \"https://w3id.org/security/bbs/v1\",\n        \"https://www.w3.org/2018/credentials/examples/v1\",\n        \"https://www.w3.org/2018/credentials/v1\"\n      ],\n      \"types\": [\n        \"UniversityDegreeCredential\",\n        \"VerifiableCredential\"\n      ],\n      \"schema_ids\": [],\n      \"issuer_id\": \"did:key:zUC71KdwBhq1FioWh53VXmyFiGpewNcg8Ld42WrSChpMzzskRWwHZfG9TJ7hPj8wzmKNrek3rW4ZkXNiHAjVchSmTr9aNUQaArK3KSkTySzjEM73FuDV62bjdAHF7EMnZ27poCE\",\n      \"subject_ids\": [],\n      \"proof_types\": [\n        \"BbsBlsSignature2020\"\n      ],\n      \"cred_value\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\",\n          \"https://w3id.org/security/bbs/v1\"\n        ],\n        \"type\": [\n          \"VerifiableCredential\",\n          \"UniversityDegreeCredential\"\n        ],\n        \"issuer\": \"did:key:zUC71Kd...poCE\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"givenName\": \"Sally\",\n          \"familyName\": \"Student\",\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"degreeType\": \"Undergraduate\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        },\n        \"proof\": {\n          \"type\": \"BbsBlsSignature2020\",\n          \"proofPurpose\": \"assertionMethod\",\n          \"verificationMethod\": \"did:key:zUC71Kd...poCE#zUC71Kd...poCE\",\n          \"created\": \"2021-05-19T16:19:44.458170\",\n          \"proofValue\": \"g0weLyw2Q+niQ4pGfiXB...tL9C9ORhy9Q==\"\n        }\n      },\n      \"cred_tags\": {},\n      \"record_id\": \"365ab87b12f74b2db784fdd4db8419f5\"\n    }\n  ]\n}\n</code></pre> <p>If you don't see the credential in your wallet, look up the credential exchange record (in alice's admin api - <code>/issue-credential-2.0/records</code>) and check the state.  If the state is <code>credential-received</code>, then the credential has been received but not stored, in this case just call the <code>/store</code> endpoint for this credential exchange.</p>"},{"location":"demo/AliceWantsAJsonCredential/#building-more-realistic-json-ld-credentials","title":"Building More Realistic JSON-LD Credentials","text":"<p>The above example uses the <code>https://www.w3.org/2018/credentials/examples/v1</code> context, which should never be used in a real application.</p> <p>To build credentials in real life, you first determine which attributes you need and then include the appropriate contexts.</p>"},{"location":"demo/AliceWantsAJsonCredential/#context-schemaorg","title":"Context schema.org","text":"<p>You can use attributes defined on schema.org.  Although this is NOT RECOMMENDED (included here for illustrative purposes only) - individual attributes can't be validated (see the comment later on).</p> <p>You first include <code>https://schema.org</code> in the <code>@context</code> block of the credential as follows:</p> <pre><code>\"@context\": [\n  \"https://www.w3.org/2018/credentials/v1\",\n  \"https://schema.org\"\n],\n</code></pre> <p>Then you review the attributes and objects defined by <code>https://schema.org</code> and decide what you need to include in your credential.</p> <p>For example to issue a credetial with givenName, familyName and alumniOf attributes, submit the following:</p> <pre><code>{\n  \"connection_id\": \"ad35a4d8-c84b-4a4f-a83f-1afbf134b8b9\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://schema.org\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"Person\"],\n        \"issuer\": \"did:key:zUC71pj2gpDLfcZ9DE1bMtjZGWCSLhkQsUCaKjqXtCftGkz27894pEX9VvGNiFsaV67gqv2TEPQ2aDaDDdTDNp42LfDdK1LaWSBCfzsQEyaiR1zjZm1RtoRu1ZM6v6vz4TiqDgU\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"givenName\": \"Sally\",\n          \"familyName\": \"Student\",\n          \"alumniOf\": \"Example University\"\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre> <p>Note that with <code>https://schema.org</code>, if you include attributes that aren't defined by any context, you will not get an error.  For example you can try replacing the <code>credentialSubject</code> in the above with:</p> <pre><code>\"credentialSubject\": {\n  \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n  \"givenName\": \"Sally\",\n  \"familyName\": \"Student\",\n  \"alumniOf\": \"Example University\",\n  \"someUndefinedAttribute\": \"the value of the attribute\"\n}\n</code></pre> <p>... and the credential issuance should fail, however <code>https://schema.org</code> defines a <code>@vocab</code> that by default all terms derive from (see here).</p> <p>You can include more complex schemas, for example to use the schema.org Person schema (which includes <code>givenName</code> and <code>familyName</code>):</p> <pre><code>{\n  \"connection_id\": \"ad35a4d8-c84b-4a4f-a83f-1afbf134b8b9\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://schema.org\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"Person\"],\n        \"issuer\": \"did:key:zUC71pj2gpDLfcZ9DE1bMtjZGWCSLhkQsUCaKjqXtCftGkz27894pEX9VvGNiFsaV67gqv2TEPQ2aDaDDdTDNp42LfDdK1LaWSBCfzsQEyaiR1zjZm1RtoRu1ZM6v6vz4TiqDgU\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"student\": {\n            \"type\": \"Person\",\n            \"givenName\": \"Sally\",\n            \"familyName\": \"Student\",\n            \"alumniOf\": \"Example University\"\n          }\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"demo/AliceWantsAJsonCredential/#credential-specific-contexts","title":"Credential-Specific Contexts","text":"<p>The recommended approach to defining credentials is to define a credential-specific vocabulary (or make use of existing ones).  (Note that these can include references to <code>https://schema.org</code>, you just shouldn't uste this directly in your credential.)</p>"},{"location":"demo/AliceWantsAJsonCredential/#credential-issue-example","title":"Credential Issue Example","text":"<p>The following example uses the W3C citizenship context to issue a PermanentResident credential (replace the <code>connection_id</code>, <code>issuer</code> and <code>credentialSubject.id</code> with your local values):</p> <pre><code>{\n    \"connection_id\": \"41acd909-9f45-4c69-8641-8146e0444a57\",\n    \"filter\": {\n        \"ld_proof\": {\n            \"credential\": {\n                \"@context\": [\n                    \"https://www.w3.org/2018/credentials/v1\",\n                    \"https://w3id.org/citizenship/v1\"\n                ],\n                \"type\": [\n                    \"VerifiableCredential\",\n                    \"PermanentResident\"\n                ],\n                \"id\": \"https://credential.example.com/residents/1234567890\",\n                \"issuer\": \"did:key:zUC7Dus47jW5Avcne8LLsUvJSdwspmErgehxMWqZZy8eSSNoHZ4x8wgs77sAmQtCADED5RQP1WWhvt7KFNm6GGMxdSGpKu3PX6R9a61G9VoVsiFoRf1yoK6pzhq9jtFP3e2SmU9\",\n                \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n                \"credentialSubject\": {\n                    \"type\": [\n                        \"PermanentResident\"\n                    ],\n                    \"id\": \"did:key:zUC7CXi82AXbkv4SvhxDxoufrLwQSAo79qbKiw7omCQ3c4TyciDdb9s3GTCbMvsDruSLZX6HNsjGxAr2SMLCNCCBRN5scukiZ4JV9FDPg5gccdqE9nfCU2zUcdyqRiUVnn9ZH83\",\n                    \"givenName\": \"ALICE\",\n                    \"familyName\": \"SMITH\",\n                    \"gender\": \"Female\",\n                    \"birthCountry\": \"Bahamas\",\n                    \"birthDate\": \"1958-07-17\"\n                }\n            },\n            \"options\": {\n                \"proofType\": \"BbsBlsSignature2020\"\n            }\n        }\n    }\n}\n</code></pre> <p>Copy and paste this content into Faber's <code>/issue-credential-2.0/send-offer</code> endpoint, and it will kick off the exchange process to issue a W3C credential to Alice.</p> <p>In Alice's swagger page, submit the <code>/credentials/records/w3c</code> endpoint to see the issued credential.</p>"},{"location":"demo/AliceWantsAJsonCredential/#request-presentation-example","title":"Request Presentation Example","text":"<p>To request a proof, submit the following (with appropriate <code>connection_id</code>) to Faber's <code>/present-proof-2.0/send-request</code> endpoint:</p> <pre><code>{\n    \"comment\": \"string\",\n    \"connection_id\": \"41acd909-9f45-4c69-8641-8146e0444a57\",\n    \"presentation_request\": {\n        \"dif\": {\n            \"options\": {\n                \"challenge\": \"3fa85f64-5717-4562-b3fc-2c963f66afa7\",\n                \"domain\": \"4jt78h47fh47\"\n            },\n            \"presentation_definition\": {\n                \"id\": \"32f54163-7166-48f1-93d8-ff217bdb0654\",\n                \"format\": {\n                    \"ldp_vp\": {\n                        \"proof_type\": [\n                            \"BbsBlsSignature2020\"\n                        ]\n                    }\n                },\n                \"input_descriptors\": [\n                    {\n                        \"id\": \"citizenship_input_1\",\n                        \"name\": \"EU Driver's License\",\n                        \"schema\": [\n                            {\n                                \"uri\": \"https://www.w3.org/2018/credentials#VerifiableCredential\"\n                            },\n                            {\n                                \"uri\": \"https://w3id.org/citizenship#PermanentResident\"\n                            }\n                        ],\n                        \"constraints\": {\n                            \"limit_disclosure\": \"required\",\n                            \"is_holder\": [\n                                {\n                                    \"directive\": \"required\",\n                                    \"field_id\": [\n                                        \"1f44d55f-f161-4938-a659-f8026467f126\"\n                                    ]\n                                }\n                            ],\n                            \"fields\": [\n                                {\n                                    \"id\": \"1f44d55f-f161-4938-a659-f8026467f126\",\n                                    \"path\": [\n                                        \"$.credentialSubject.familyName\"\n                                    ],\n                                    \"purpose\": \"The claim must be from one of the specified issuers\",\n                                    \"filter\": {\n                                        \"const\": \"SMITH\"\n                                    }\n                                },\n                                {\n                                    \"path\": [\n                                        \"$.credentialSubject.givenName\"\n                                    ],\n                                    \"purpose\": \"The claim must be from one of the specified issuers\"\n                                }\n                            ]\n                        }\n                    }\n                ]\n            }\n        }\n    }\n}\n</code></pre> <p>Note that the <code>is_holder</code> property can be used by Faber to verify that the holder of credential is the same as the subject of the attribute (<code>familyName</code>). Later on, the received presentation will be signed and verifiable only if <code>is_holder</code> with <code>\"directive\": \"required\"</code> is included in the presentation request.</p> <p>There are several ways that Alice can respond with a presentation.  The simplest will just tell ACA-Py to put the presentation together and send it to Faber - submit the following to Alice's <code>/present-proof-2.0/records/{pres_ex_id}/send-presentation</code>:</p> <pre><code>{\n  \"dif\": {\n  }\n}\n</code></pre> <p>There are two ways that Alice can provide some constraints to tell ACA-Py which credential(s) to include in the presentation.</p> <p>Firstly, Alice can include the received presentation request in the body to the <code>/send-presentation</code> endpoint, and can include additional constraints on the fields:</p> <pre><code>{\n  \"dif\": {\n    \"issuer_id\": \"did:key:zUC7Dus47jW5Avcne8LLsUvJSdwspmErgehxMWqZZy8eSSNoHZ4x8wgs77sAmQtCADED5RQP1WWhvt7KFNm6GGMxdSGpKu3PX6R9a61G9VoVsiFoRf1yoK6pzhq9jtFP3e2SmU9\",\n    \"presentation_definition\": {\n      \"format\": {\n        \"ldp_vp\": {\n          \"proof_type\": [\n            \"BbsBlsSignature2020\"\n          ]\n        }\n      },\n      \"id\": \"32f54163-7166-48f1-93d8-ff217bdb0654\",\n      \"input_descriptors\": [\n        {\n          \"id\": \"citizenship_input_1\",\n          \"name\": \"Some kind of citizenship check\",\n          \"schema\": [\n            {\n              \"uri\": \"https://www.w3.org/2018/credentials#VerifiableCredential\"\n            },\n            {\n              \"uri\": \"https://w3id.org/citizenship#PermanentResident\"\n            }\n          ],\n          \"constraints\": {\n            \"limit_disclosure\": \"required\",\n            \"is_holder\": [\n                {\n                    \"directive\": \"required\",\n                    \"field_id\": [\n                        \"1f44d55f-f161-4938-a659-f8026467f126\",\n                        \"332be361-823a-4863-b18b-c3b930c5623e\"\n                    ],\n                }\n            ],\n            \"fields\": [\n              {\n                \"id\": \"1f44d55f-f161-4938-a659-f8026467f126\",\n                \"path\": [\n                  \"$.credentialSubject.familyName\"\n                ],\n                \"purpose\": \"The claim must be from one of the specified issuers\",\n                \"filter\": {\n                  \"const\": \"SMITH\"\n                }\n              },\n              {\n                  \"id\": \"332be361-823a-4863-b18b-c3b930c5623e\",\n                  \"path\": [\n                      \"$.id\"\n                  ],\n                  \"purpose\": \"Specify the id of the credential to present\",\n                  \"filter\": {\n                      \"const\": \"https://credential.example.com/residents/1234567890\"\n                  }\n              }\n            ]\n          }\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>Note the additional constraint on <code>\"path\": [ \"$.id\" ]</code> - this restricts the presented credential to the one with the matching <code>credential.id</code>.  Any credential attributes can be used, however this presumes that the issued credentials contain a uniquely identifying attribute.</p> <p>Another option is for Alice to specify the credential <code>record_id</code> - this is an internal value within ACA-Py:</p> <pre><code>{\n  \"dif\": {\n    \"issuer_id\": \"did:key:zUC7Dus47jW5Avcne8LLsUvJSdwspmErgehxMWqZZy8eSSNoHZ4x8wgs77sAmQtCADED5RQP1WWhvt7KFNm6GGMxdSGpKu3PX6R9a61G9VoVsiFoRf1yoK6pzhq9jtFP3e2SmU9\",\n    \"presentation_definition\": {\n      \"format\": {\n        \"ldp_vp\": {\n          \"proof_type\": [\n            \"BbsBlsSignature2020\"\n          ]\n        }\n      },\n      \"id\": \"32f54163-7166-48f1-93d8-ff217bdb0654\",\n      \"input_descriptors\": [\n        {\n          \"id\": \"citizenship_input_1\",\n          \"name\": \"Some kind of citizenship check\",\n          \"schema\": [\n            {\n              \"uri\": \"https://www.w3.org/2018/credentials#VerifiableCredential\"\n            },\n            {\n              \"uri\": \"https://w3id.org/citizenship#PermanentResident\"\n            }\n          ],\n          \"constraints\": {\n            \"limit_disclosure\": \"required\",\n            \"fields\": [\n              {\n                \"path\": [\n                  \"$.credentialSubject.familyName\"\n                ],\n                \"purpose\": \"The claim must be from one of the specified issuers\",\n                \"filter\": {\n                  \"const\": \"SMITH\"\n                }\n              }\n            ]\n          }\n        }\n      ]\n    },\n    \"record_ids\": {\n      \"citizenship_input_1\": [ \"1496316f972e40cf9b46b35971182337\" ]\n    }\n  }\n}\n</code></pre>"},{"location":"demo/AliceWantsAJsonCredential/#another-credential-issue-example","title":"Another Credential Issue Example","text":"<p>TBD the following credential is based on the W3C Vaccination schema:</p> <pre><code>{\n  \"connection_id\": \"ad35a4d8-c84b-4a4f-a83f-1afbf134b8b9\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://w3id.org/vaccination/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"VaccinationCertificate\"],\n        \"issuer\": \"did:key:zUC71pj2gpDLfcZ9DE1bMtjZGWCSLhkQsUCaKjqXtCftGkz27894pEX9VvGNiFsaV67gqv2TEPQ2aDaDDdTDNp42LfDdK1LaWSBCfzsQEyaiR1zjZm1RtoRu1ZM6v6vz4TiqDgU\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n            \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n            \"type\": \"VaccinationEvent\",\n            \"batchNumber\": \"1183738569\",\n            \"administeringCentre\": \"MoH\",\n            \"healthProfessional\": \"MoH\",\n            \"countryOfVaccination\": \"NZ\",\n            \"recipient\": {\n              \"type\": \"VaccineRecipient\",\n              \"givenName\": \"JOHN\",\n              \"familyName\": \"SMITH\",\n              \"gender\": \"Male\",\n              \"birthDate\": \"1958-07-17\"\n            },\n            \"vaccine\": {\n              \"type\": \"Vaccine\",\n              \"disease\": \"COVID-19\",\n              \"atcCode\": \"J07BX03\",\n              \"medicinalProductName\": \"COVID-19 Vaccine Moderna\",\n              \"marketingAuthorizationHolder\": \"Moderna Biotech\"\n            }\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"demo/AriesOpenAPIDemo/","title":"Aries OpenAPI Demo","text":"<p>What better way to learn about controllers than by actually being one yourself! In this demo, that\u2019s just what happens\u2014you are the controller. You have access to the full set of API endpoints exposed by an ACA-Py instance, and you will see the events coming from ACA-Py as they happen. Using that information, you'll help Alice's and Faber's agents connect, Faber's agent issue an education credential to Alice, and then ask Alice to prove she possesses the credential. Who knows why Faber needs to get the proof, but it lets us show off more protocols.</p>"},{"location":"demo/AriesOpenAPIDemo/#contents","title":"Contents","text":"<ul> <li>Getting Started</li> <li>Running in a Browser</li> <li>Start the Faber Agent</li> <li>Start the Alice Agent</li> <li>Running in Docker</li> <li>Start the Faber Agent</li> <li>Start the Alice Agent</li> <li>Restarting the Docker Containers</li> <li>Using the OpenAPI/Swagger User Interface</li> <li>Establishing a Connection</li> <li>Use the Faber Agent to Create an Invitation</li> <li>Copy the Invitation created by the Faber Agent</li> <li>Use the Alice Agent to Receive Faber's Invitation</li> <li>Tell Alice's Agent to Accept the Invitation</li> <li>The Faber Agent Gets the Request</li> <li>The Faber Agent Completes the Connection</li> <li>Review the Connection Status in Alice's Agent</li> <li>Review the Connection Status in Faber's Agent</li> <li>Basic Messaging Between Agents</li> <li>Sending a message from Alice to Faber</li> <li>Receiving a Basic Message (Faber)</li> <li>Alice's Agent Verifies that Faber has Received the Message</li> <li>Preparing to Issue a Credential</li> <li>Confirming your Schema and Credential Definition</li> <li>Notes</li> <li>Issuing a Credential</li> <li>Faber - Preparing to Issue a Credential</li> <li>Faber - Issuing the Credential</li> <li>Alice Receives Credential</li> <li>Alice Stores Credential in her Wallet</li> <li>Faber Receives Acknowledgment that the Credential was Received</li> <li>Issue Credential Notes</li> <li>Bonus Points</li> <li>Requesting/Presenting a Proof</li> <li>Faber sends a Proof Request</li> <li>Alice - Responding to the Proof Request</li> <li>Faber - Verifying the Proof</li> <li>Present Proof Notes</li> <li>Bonus Points</li> <li>Conclusion</li> </ul>"},{"location":"demo/AriesOpenAPIDemo/#getting-started","title":"Getting Started","text":"<p>We will get started by opening three browser tabs that will be used throughout the lab. Two will be Swagger UIs for the Faber and Alice agent and one for the public ledger (showing the Hyperledger Indy ledger). As well, we'll keep the terminal sessions where we started the demos handy, as we'll be grabbing information from them as well.</p> <p>Let's start with the ledger browser. For this demo, we're going to use an open public ledger operated by the BC Government's VON Team. In your first browser tab, go to: http://test.bcovrin.vonx.io. This will be called the \"ledger tab\" in the instructions below.</p> <p>For the rest of the set up, you can choose to run the terminal sessions in your browser (no local resources needed), or you can run it in Docker on your local system. Your choice, each is covered in the next two sections.</p> <p>Note: In the following, when we start the agents we use several special demo settings. The command we use is this: <code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events --no-auto --bg</code>. In that:</p> <ul> <li>The <code>LEDGER_URL</code> environment variable informs the agent what ledger to use.</li> <li>The <code>--events</code> option indicates that we want the controller to display the webhook events from ACA-Py in the log displayed on the terminal.</li> <li>The <code>--no-auto</code> option indicates that we don't want the ACA-Py agent to automatically handle some events such as connecting. We want the controller (you!) to handle each step of the protocol.</li> <li>The <code>--bg</code> option indicates that the docker container will run in the background, so accidentally hitting Ctrl-C won't stop the process.</li> </ul>"},{"location":"demo/AriesOpenAPIDemo/#running-in-a-browser","title":"Running in a Browser","text":"<p>To run the necessary terminal sessions in your browser, go to the Docker playground service Play with Docker. Don't know about Play with Docker? Check this out to learn more.</p>"},{"location":"demo/AriesOpenAPIDemo/#start-the-faber-agent","title":"Start the Faber Agent","text":"<p>In a browser, go to the Play with Docker home page, Login (if necessary) and click \"Start.\" On the next screen, click (in the left menu) \"+Add a new instance.\"  That will start up a terminal in your browser. Run the following commands to start the Faber agent.</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f faber\n</code></pre> <p>Once the Faber agent has started up (with the invite displayed), click the link near the top of the screen <code>8021</code>. That will start an instance of the OpenAPI/Swagger user interface connected to the Faber instance. Note that the URL on the OpenAPI/Swagger instance is: <code>http://ip....8021.direct...</code>.</p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8021 is the Faber agent.</p> <p>NOTE: Hit \"Ctrl-C\" at any time to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Faber agent by running <code>docker logs -f faber</code></p> Show me a screenshot!"},{"location":"demo/AriesOpenAPIDemo/#start-the-alice-agent","title":"Start the Alice Agent","text":"<p>Now to start Alice's agent. Click the \"+Add a new instance\" button again to open another terminal session. Run the following commands to start Alice's agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f alice\n</code></pre> <p>You can ignore a message like <code>WARNING: your terminal doesn't support cursor position requests (CPR).</code></p> <p>Once the Alice agent has started up (with the <code>invite:</code> prompt displayed), click the link near the top of the screen <code>8031</code>. That will start an instance of the OpenAPI/Swagger User Interface connected to the Alice instance. Note that the URL on the OpenAPI/Swagger instance is: <code>http://ip....8031.direct...</code>.</p> <p>NOTE: Hit \"Ctrl-C\" to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Faber agent by running <code>docker logs -f faber</code></p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8031 is Alice's agent.</p> Show me a screenshot! <p>You are ready to go. Skip down to the Using the OpenAPI/Swagger User Interface section.</p>"},{"location":"demo/AriesOpenAPIDemo/#running-in-docker","title":"Running in Docker","text":"<p>To run the demo on your local system, you must have git, a running Docker installation, and terminal windows running bash. Need more information about getting set up? Click here to learn more.</p>"},{"location":"demo/AriesOpenAPIDemo/#start-the-faber-agent_1","title":"Start the Faber Agent","text":"<p>To begin running the demo in Docker, open up two terminal windows, one each for Faber\u2019s and Alice\u2019s agent.</p> <p>In the first terminal window, clone the ACA-Py repo, change into the demo folder and start the Faber agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f faber\n</code></pre> <p>If all goes well, the agent will show a message indicating it is running. Use the second browser tab to navigate to http://localhost:8021. You should see an OpenAPI/Swagger user interface with a (long-ish) list of API endpoints. These are the endpoints exposed by the Faber agent.</p> <p>NOTE: Hit \"Ctrl-C\" to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Faber agent by running <code>docker logs -f faber</code></p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8021 is the Faber agent.</p> Show me a screenshot!"},{"location":"demo/AriesOpenAPIDemo/#start-the-alice-agent_1","title":"Start the Alice Agent","text":"<p>To start Alice's agent, open up a second terminal window and in it, change to the same <code>demo</code> directory as where Faber's agent was started above. Once there, start Alice's agent:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f alice\n</code></pre> <p>You can ignore a message like <code>WARNING: your terminal doesn't support cursor position requests (CPR)</code> that may appear.</p> <p>If all goes well, the agent will show a message indicating it is running. Open a third browser tab and navigate to http://localhost:8031. Again, you should see the OpenAPI/Swagger user interface with a list of API endpoints, this time the endpoints for Alice\u2019s agent.</p> <p>NOTE: Hit \"Ctrl-C\" to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Alice agent by running <code>docker logs -f alice</code></p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8031 is Alice's agent.</p> Show me a screenshot!"},{"location":"demo/AriesOpenAPIDemo/#restarting-the-docker-containers","title":"Restarting the Docker Containers","text":"<p>When you complete the entire demo (not now!!), you can need to stop the two agents.  To do that, get to the command line by hitting Ctrl-C and running:</p> <pre><code>docker stop faber\ndocker stop alice\n</code></pre>"},{"location":"demo/AriesOpenAPIDemo/#using-the-openapiswagger-user-interface","title":"Using the OpenAPI/Swagger User Interface","text":"<p>Try to organize what you see on your screen to include both the Alice and Faber OpenAPI/Swagger tabs, and both (Alice and Faber) terminal sessions, all at the same time. After you execute an API call in one of the browser tabs, you will see a webhook event from the ACA-Py instance in the terminal window of the other agent. That's a controller's life. See an event, process it, send a response.</p> <p>From time to time you will want to see what's happening on the ledger, so keep that handy as well. As well, if you make an error with one of the commands (e.g. bad data, improperly structured JSON), you will see the errors in the terminals.</p> <p>In the instructions that follow, we\u2019ll let you know if you need to be in the Faber, Alice or Indy browser tab. We\u2019ll leave it to you to track which is which.</p> <p>Using the OpenAPI/Swagger user interface is pretty simple. In the steps below, we\u2019ll indicate what API endpoint you need use, such as <code>POST /connections/create-invitation</code>. That means you must:</p> <ol> <li>scroll to and find that endpoint;</li> <li>click on the endpoint name to expand its section of the UI;</li> <li>click on the <code>Try it out</code> button;</li> <li>fill in any data necessary to run the command;</li> <li>click <code>Execute</code>;</li> <li>check the response to see if the request worked.</li> </ol> <p>So, the mechanical steps are easy. It\u2019s fourth step from the list above that can be tricky. Supplying the right data and, where JSON is involved, getting the syntax correct - braces and quotes can be a pain. When steps don\u2019t work, start your debugging by looking at your JSON.</p> <p>Enough with the preliminaries, let\u2019s get started!</p>"},{"location":"demo/AriesOpenAPIDemo/#establishing-a-connection","title":"Establishing a Connection","text":"<p>We\u2019ll start the demo by establishing a connection between the Alice and Faber agents. We\u2019re starting there to demonstrate that you can use agents without having a ledger. We won\u2019t be using the Indy public ledger at all for this step. Since the agents communicate using DIDComm messaging and connect by exchanging pairwise DIDs and DIDDocs based on (an early version of) the <code>did:peer</code> DID method, a public ledger is not needed.</p>"},{"location":"demo/AriesOpenAPIDemo/#use-the-faber-agent-to-create-an-invitation","title":"Use the Faber Agent to Create an Invitation","text":"<p>In the Faber browser tab, navigate to the <code>POST /connections/create-invitation</code> endpoint. Replace the sample body with and empty production (<code>{}</code>) and execute the call. If successful, you should see a connection id, an invitation, and the invitation URL. The connection ids will be different on each run.</p> <p>Hint: set an Alias on the Invitation, this makes it easier to find the Connection later on</p> Show me a screenshot - Create Invitation Request Show me a screenshot - Create Invitation Response"},{"location":"demo/AriesOpenAPIDemo/#copy-the-invitation-created-by-the-faber-agent","title":"Copy the Invitation created by the Faber Agent","text":"<p>Copy the entire block of the <code>invitation</code> object, from the curly brackets <code>{}</code>, excluding the trailing comma.</p> Show me a screenshot - Create Invitation Response <p>Before switching over to the Alice browser tab, scroll to and execute  the <code>GET /connections</code> endpoint to see the list of Faber's connections. You should see a connection with a <code>connection_id</code> that is identical to the invitation you just created, and that its state is <code>invitation</code>.</p> Show me a screenshot - Faber Connection Status"},{"location":"demo/AriesOpenAPIDemo/#use-the-alice-agent-to-receive-fabers-invitation","title":"Use the Alice Agent to Receive Faber's Invitation","text":"<p>Switch to the Alice browser tab and get ready to execute the <code>POST /connections/receive-invitation</code> endpoint. Select all of the pre-populated text and replace it with the invitation object from the Faber tab. When you click <code>Execute</code> you should get back a connection response with a connection Id, an invitation key, and the state of the connection, which should be <code>invitation</code>.</p> <p>Hint: set an Alias on the Invitation, this makes it easier to find the Connection later on</p> Show me a screenshot - Receive Invitation Request Show me a screenshot - Receive Invitation Response <p>A key observation to make here. The \"copy and paste\" we are doing here from Faber's agent to Alice's agent is what is called an \"out of band\" message. Because we don't yet have a DIDComm connection between the two agents, we have to convey the invitation in plaintext (we can't encrypt it - no channel) using some other mechanism than DIDComm. With mobile agents, that's where QR codes often come in. Once we have the invitation in the receivers agent, we can get back to using DIDComm.</p>"},{"location":"demo/AriesOpenAPIDemo/#tell-alices-agent-to-accept-the-invitation","title":"Tell Alice's Agent to Accept the Invitation","text":"<p>At this point Alice has simply stored the invitation in her wallet. You can see the status using the <code>GET /connections</code> endpoint.</p> Show me a screenshot <p>To complete a connection with Faber, she must accept the invitation and send a corresponding connection request to Faber. Find the <code>connection_id</code> in the connection response from the previous <code>POST /connections/receive-invitation</code> endpoint call. You may note that the same data was sent to the controller as an event from ACA-Py and is visible in the terminal. Scroll to the <code>POST /connections/{conn_id}/accept-invitation</code> endpoint and paste the <code>connection_id</code> in the <code>id</code> parameter field (you will have to click the <code>Try it out</code> button to see the available URL parameters). The response from clicking <code>Execute</code> should show that the connection has a state of <code>request</code>.</p> Show me a screenshot - Accept Invitation Request Show me a screenshot - Accept Invitation Response"},{"location":"demo/AriesOpenAPIDemo/#the-faber-agent-gets-the-request","title":"The Faber Agent Gets the Request","text":"<p>In the Faber terminal session, an event (a web service callback from ACA-Py to the controller) has been received about the request from Alice. Copy the <code>connection_id</code> from the event for the next step.</p> Show me the event <p>Note that the connection ID held by Alice is different from the one held by Faber. That makes sense, as both independently created connection objects, each with a unique, self-generated GUID.</p>"},{"location":"demo/AriesOpenAPIDemo/#the-faber-agent-completes-the-connection","title":"The Faber Agent Completes the Connection","text":"<p>To complete the connection process, Faber will respond to the connection request from Alice. Scroll to the <code>POST /connections/{conn_id}/accept-request</code> endpoint and paste the <code>connection_id</code> you previously copied into the <code>id</code> parameter field (you will have to click the <code>Try it out</code> button to see the available URL parameters). The response from clicking the <code>Execute</code> button should show that the connection has a state of <code>response</code>, which indicates that Faber has accepted Alice's connection request.</p> Show me a screenshot - Accept Connection Request Show me a screenshot - Accept Connection Request"},{"location":"demo/AriesOpenAPIDemo/#review-the-connection-status-in-alices-agent","title":"Review the Connection Status in Alice's Agent","text":"<p>Switch over to the Alice browser tab.</p> <p>Scroll to and execute <code>GET /connections</code> to see a list of Alice's connections, and the information tracked about each connection. You should see the one connection Alice\u2019s agent has, that it is with the Faber agent, and that its state is <code>active</code>.</p> Show me a screenshot - Alice Connection Status <p>As with Faber's side of the connection, Alice received a notification that Faber had accepted her connection request.</p> Show me the event"},{"location":"demo/AriesOpenAPIDemo/#review-the-connection-status-in-fabers-agent","title":"Review the Connection Status in Faber's Agent","text":"<p>You are connected! Switch to the Faber browser tab and run the same <code>GET /connections</code> endpoint to see Faber's view of the connection. Its state is also <code>active</code>. Note the <code>connection_id</code>, you\u2019ll need it later in the tutorial.</p> Show me a screenshot - Faber Connection Status"},{"location":"demo/AriesOpenAPIDemo/#basic-messaging-between-agents","title":"Basic Messaging Between Agents","text":"<p>Once you have a connection between two agents, you have a channel to exchange secure, encrypted messages. In fact these underlying encrypted messages (similar to envelopes in a postal system) enable the delivery of messages that form the higher level protocols, such as issuing Credentials and providing Proofs. So, let's send a couple of messages that contain the simplest of context\u2014text. For this we wil use the Basic Message protocol, Aries RFC 0095.</p>"},{"location":"demo/AriesOpenAPIDemo/#sending-a-message-from-alice-to-faber","title":"Sending a message from Alice to Faber","text":"<p>On Alice's swagger page, scroll to the <code>POST /connections/{conn_id}/send-message</code> endpoint. Click on <code>Try it Out</code> and enter a message in the body provided (for example <code>{\"content\": \"Hello Faber\"}</code>). Enter the connection id of Alice's connection in the field provided. Then click on <code>Execute</code>.</p> Show me a screenshot"},{"location":"demo/AriesOpenAPIDemo/#receiving-a-basic-message-faber","title":"Receiving a Basic Message (Faber)","text":"<p>How does Faber know that a message was sent? If you take a look at Faber's console window, you can see that Faber's agent has raised an Event that the message was received:</p> Show me a screenshot <p>Faber's controller application can take whatever action is necessary to process this message. It could trigger some application code, or it might just be something the Faber application needs to display to its user (for example a reminder about some action the user needs to take).</p>"},{"location":"demo/AriesOpenAPIDemo/#alices-agent-verifies-that-faber-has-received-the-message","title":"Alice's Agent Verifies that Faber has Received the Message","text":"<p>How does Alice get feedback that Faber has received the message? The same way - when Faber's agent acknowledges receipt of the message, Alice's agent raises an Event to let the Alice controller know:</p> Show me a screenshot <p>Again, Alice's agent can take whatever action is necessary, possibly just flagging the message as having been <code>received</code>.</p>"},{"location":"demo/AriesOpenAPIDemo/#preparing-to-issue-a-credential","title":"Preparing to Issue a Credential","text":"<p>The next thing we want to do in the demo is have the Faber agent issue a credential to Alice\u2019s agent. To this point, we have not used the Indy ledger at all. Establishing the connection and messaging has been done with pairwise DIDs based on the <code>did:peer</code> method. Verifiable credentials must be rooted in a public DID ledger to enable the presentation of proofs.</p> <p>Before the Faber agent can issue a credential, it must register a DID on the Indy public ledger, publish a schema, and create a credential definition. In the \u201creal world\u201d, the Faber agent would do this before connecting with any other agents. And, since we are using the handy \"./run_demo faber\" (and \"./run_demo alice\") scripts to start up our agents, the Faber version of the script has already:</p> <ol> <li>registered a public DID and stored it on the ledger;</li> <li>created a schema and registered it on the ledger;</li> <li>created a credential definition and registered it on the ledger.</li> </ol> <p>The schema and credential definition could also be created through this swagger interface.</p> <p>We don't cover the details of those actions in this tutorial, but there are other materials available that go through these details.</p> <p>To Do: Add a link to directions for doing this manually, and to where in the controller Python code this is done.</p>"},{"location":"demo/AriesOpenAPIDemo/#confirming-your-schema-and-credential-definition","title":"Confirming your Schema and Credential Definition","text":"<p>You can confirm the schema and credential definition were published by going back to the Indy ledger browser tab using Faber's public DID. You may have saved that from a previous step, but if not here is an API call you can make to get that information. Using Faber's swagger page and scroll to the <code>GET /wallet/did/public</code> endpoint. Click on <code>Try it Out</code> and <code>Execute</code> and you will see Faber's public DID.</p> Show me a screenshot <p>On the ledger browser of the BCovrin ledger, click the <code>Domain</code> page, refresh, and paste the Faber public DID into the <code>Filter:</code> field:</p> Show me a screenshot <p>The ledger browser should refresh and display the four (4) transactions on the ledger related to this DID:</p> <ul> <li>the initial DID registration</li> <li>registration of the DID endpoint (Faber is an issuer so it has a public endpoint)</li> <li>the registered schema</li> <li>the registered credential definition</li> </ul> Show me the ledger transactions <p>You can also look up the Schema and Credential Definition information using Faber's swagger page. Use the <code>GET /schemas/created</code> endpoint to get a list of schemas, including the one <code>schema_id</code> that the Faber agent has defined. Keep this section of the Swagger page expanded as we'll need to copy the Id as part of starting the issue credential protocol coming next.</p> Show me a screenshot <p>Likewise use the <code>GET /credential-definitions/created</code> endpoint to get the list of the one (in this case) credential definition id created by Faber. Keep this section of the Swagger page expanded as we'll also need to copy the Id as part of starting the issue credential protocol coming next.</p> Show me a screenshot <p>Hint: Remember how the schema and credential definitions were created for you as Faber started up? To do it yourself, use the <code>POST</code> versions of these endpoints. Now you know!</p>"},{"location":"demo/AriesOpenAPIDemo/#notes","title":"Notes","text":"<p>The one time setup work for issuing a credential is complete\u2014creating a DID, schema and credential definition. We can now issue 1 or 1 million credentials without having to do those steps again. Astute readers might note that we did not setup a revocation registry, so we cannot revoke the credentials we issue with that credential definition. You can\u2019t have everything in an \"easy\" tutorial!</p>"},{"location":"demo/AriesOpenAPIDemo/#issuing-a-credential","title":"Issuing a Credential","text":"<p>Triggering the issuance of a credential from the Faber agent to Alice\u2019s agent is done with another API call. In the Faber browser tab, scroll down to the <code>POST /issue-credential-2.0/send</code> and get ready to (but don\u2019t yet) execute the request. Before execution, you need to update most of the data elements in the JSON. We now cover how to update all the fields.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-preparing-to-issue-a-credential","title":"Faber - Preparing to Issue a Credential","text":"<p>First, get the connection Id for Faber's connection with Alice. You can copy that from the Faber terminal (the last received event includes it), or scroll up on the Faber swagger tab to the <code>GET /connections</code> API endpoint, execute, copy it and paste the <code>connection_id</code> value into the same field in the issue credential JSON.</p> Click here to see a screenshot <p>For the following fields, scroll on Faber's Swagger page to the listed endpoint, execute (if necessary), copy the response value and paste as the values of the following JSON items:</p> <ul> <li><code>issuer_did</code> the Faber public DID (use <code>GET /wallet/DID/public</code>), </li> <li><code>schema_id</code> the Id of the schema Faber created (use <code>GET /schemas/created</code>) and,</li> <li><code>cred_def_id</code> the Id of the credential definition Faber created (use <code>GET /credential-definitions/created</code>)</li> </ul> <p>into the <code>filter</code> section's <code>indy</code> subsection. Remove the <code>\"dif\"</code> subsection of the <code>filter</code> section within the JSON, and specify the remaining indy filter criteria as follows:</p> <ul> <li><code>schema_version</code>: set to the last segment of the <code>schema_id</code>, a three part version number that was randomly generated on startup of the Faber agent. Segments of the <code>schema_id</code> are separated by \":\"s.</li> <li><code>schema_issuer_did</code>: set to the same the value as in <code>issuer_did</code>,</li> <li><code>schema_name</code>: set to the second last segment of the <code>schema_id</code>, in this case <code>degree schema</code></li> </ul> <p>Finally, set the remaining values as follows: - <code>auto_remove</code>: set to <code>true</code> (no quotes), see note below - <code>comment</code>: set to any string. It's intended to let Alice know something about the credential being offered. - <code>trace</code>: set to <code>false</code> (no quotes). It's for troubleshooting, performance profiling, and/or diagnostics.</p> <p>By setting <code>auto_remove</code> to true, ACA-Py will automatically remove the credential exchange record after the protocol completes. When implementing a controller, this is the likely setting to use to reduce agent storage usage, but implies if a record of the issuance of the credential is needed, the controller must save it somewhere else. For example, Faber College might extend their Student Information System, where they track all their students, to record when credentials are issued to students, and the Ids of the issued credentials.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-issuing-the-credential","title":"Faber - Issuing the Credential","text":"<p>Finally, we need put into the JSON the data values for the <code>credential_preview</code> section of the JSON. Copy the following and paste it between the square brackets of the <code>attributes</code> item, replacing what is there. Feel free to change the attribute <code>value</code> items, but don't change the labels or names:</p> <pre><code>      {\n        \"name\": \"name\",\n        \"value\": \"Alice Smith\"\n      },\n      {\n        \"name\": \"timestamp\",\n        \"value\": \"1234567890\"\n      },\n      {\n        \"name\": \"date\",\n        \"value\": \"2018-05-28\"\n      },\n      {\n        \"name\": \"degree\",\n        \"value\": \"Maths\"\n      },\n      {\n        \"name\": \"birthdate_dateint\",\n        \"value\": \"19640101\"\n      }\n</code></pre> <p>(Note that the birthdate above is used to present later on to pass an \"age proof\".)</p> <p>OK, finally, you are ready to click <code>Execute</code>. The request should work, but if it doesn\u2019t - check your JSON! Did you get all the quotes and commas right?</p> Show me a screenshot - credential offer <p>To confirm the issuance worked, scroll up on the Faber Swagger page to the <code>issue-credential v2.0</code> section and execute the <code>GET /issue-credential-2.0/records</code> endpoint. You should see a lot of information about the exchange just initiated.</p>"},{"location":"demo/AriesOpenAPIDemo/#alice-receives-credential","title":"Alice Receives Credential","text":"<p>Let\u2019s look at it from Alice\u2019s side. Alice's agent source code automatically handles credential offers by immediately responding with a credential request. Scroll back in the Alice terminal to where the credential issuance started. If you've followed the full script, that is just after where we used the basic message protocol to send text messages between Alice and Faber.</p> <p>Alice's agent first received a notification of a Credential Offer, to which it responded with a Credential Request. Faber received the Credential Request and responded in turn with an Issue Credential message. Scroll down through the events from ACA-Py to the controller to see the notifications of those messages. Make sure you scroll all the way to the bottom of the terminal so you can continue with the process.</p> Show me a screenshot - issue credential"},{"location":"demo/AriesOpenAPIDemo/#alice-stores-credential-in-her-wallet","title":"Alice Stores Credential in her Wallet","text":"<p>We can check (via Alice's Swagger interface) the issue credential status by hitting the <code>GET /issue-credential-2.0/records</code> endpoint. Note that within the results, the <code>cred_ex_record</code> just received has a <code>state</code> of <code>credential-received</code>, but not yet <code>done</code>. Let's address that.</p> Show me a screenshot - check credential exchange status <p>First, we need the <code>cred_ex_id</code> from the API call response above, or from the event in the terminal; use the endpoint <code>POST /issue-credential-2.0/records/{cred_ex_id}/store</code> to tell Alice's ACA-Py instance to store the credential in agent storage (aka the Indy Wallet). Note that in the JSON for that endpoint we can provide a credential Id to store in the wallet by setting a value in the <code>credential_id</code> string. A real controller might use the <code>cred_ex_id</code> for that, or use something else that makes sense in the agent's business scenario (but the agent generates a random credential identifier by default).</p> Show me a screenshot - store credential <p>Now, in Alice\u2019s swagger browser tab, find the <code>credentials</code> section and within that, execute the <code>GET /credentials</code> endpoint. There should be a list of credentials held by Alice, with just a single entry, the credential issued from the Faber agent. Note that the element <code>referent</code> is the value of the <code>credential_id</code> element used in other calls. <code>referent</code> is the name returned in the <code>indy-sdk</code> call to get the set of credentials for the wallet and ACA-Py code does not change it in the response.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-receives-acknowledgment-that-the-credential-was-received","title":"Faber Receives Acknowledgment that the Credential was Received","text":"<p>On the Faber side, we can see by scanning back in the terminal that it receive events to notify that the credential was issued and accepted.</p> Show me Faber's event activity <p>Note that once the credential processing completed, Faber's agent deleted the credential exchange record from its wallet. This can be confirmed by executing the endpoint <code>GET /issue-credential-2.0/records</code></p> Show me a screenshot <p>You\u2019ve done it, issued a credential!  w00t!</p>"},{"location":"demo/AriesOpenAPIDemo/#issue-credential-notes","title":"Issue Credential Notes","text":"<p>Those that know something about the Indy process for issuing a credential and the DIDComm <code>Issue Credential</code> protocol know that there multiple steps to issuing credentials, a back and forth between the issuer and the holder to (at least) offer, request and issue the credential. All of those messages happened, but the two agents took care of those details rather than bothering the controller (you, in this case) with managing the back and forth.</p> <ul> <li>On the Faber agent side, this is because we used the <code>POST /issue-credential-2.0/send</code> administrative message, which handles the back and forth for the issuer automatically. We could have used the other <code>/issue-credential-2.0/</code> endpoints to allow the controller to handle each step of the protocol.</li> <li>On Alice's agent side, this is because the handler for the <code>issue_credential_v2_0</code> event always responds to credential offers with corresponding credential requests.</li> </ul>"},{"location":"demo/AriesOpenAPIDemo/#bonus-points","title":"Bonus Points","text":"<p>If you would like to perform all of the issuance steps manually on the Faber agent side, use a sequence of the other <code>/issue-credential-2.0/</code> messages. Use the <code>GET /issue-credential-2.0/records</code> to both check the credential exchange state as you progress through the protocol and to find some of the data you\u2019ll need in executing the sequence of requests.</p> <p>The following table lists endpoints that you need to call (\"REST service\") and callbacks that your agent will receive (\"callback\") that your need to respond to. See the detailed API docs.</p> Protocol Step Faber (Issuer) Alice (Holder) Notes Send Credential Offer <code>POST /issue-credential-2.0/send-offer</code> REST service Receive Offer /issue_credential_v2_0/ callback Send Credential Request <code>POST /issue-credential-2.0/records/{cred_ex_id}/send-request</code> REST service Receive Request /issue_credential_v2_0/ callback Issue Credential <code>POST /issue-credential-2.0/records/{cred_ex_id}/issue</code> REST service Receive Credential /issue_credential_v2_0/ callback Store Credential <code>POST /issue-credential-2.0/records/{cred_ex_id}/store</code> REST service Receive Acknowledgement /issue_credential_v2_0/ callback Store Credential Id application function"},{"location":"demo/AriesOpenAPIDemo/#requestingpresenting-a-proof","title":"Requesting/Presenting a Proof","text":"<p>Alice now has her Faber credential. Let\u2019s have the Faber agent send a request for a presentation (a proof) using that credential. This should be pretty easy for you at this point.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-sends-a-proof-request","title":"Faber sends a Proof Request","text":"<p>From the Faber browser tab, get ready to execute the <code>POST /present-proof-2.0/send-request</code> endpoint. After hitting <code>Try it Now</code>, erase the data in the block labelled \"Edit Value Model\", replacing it with the text below. Once that is done, replace in the JSON each instance of <code>cred_def_id</code> (there are four instances) and <code>connection_id</code> with the values found using the same techniques we've used earlier in this tutorial. Both can be found by scrolling back a little in the Faber terminal, or you can execute API endpoints we've already covered. You can also change the value of the <code>comment</code> item to whatever you want.</p> <pre><code>{\n  \"comment\": \"This is a comment about the reason for the proof\",\n  \"connection_id\": \"e469e0f3-2b4d-4b12-9ac7-293f23e8a816\",\n  \"presentation_request\": {\n    \"indy\": {\n      \"name\": \"Proof of Education\",\n      \"version\": \"1.0\",\n      \"requested_attributes\": {\n        \"0_name_uuid\": {\n          \"name\": \"name\",\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        },\n        \"0_date_uuid\": {\n          \"name\": \"date\",\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        },\n        \"0_degree_uuid\": {\n          \"name\": \"degree\",\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        },\n        \"0_self_attested_thing_uuid\": {\n          \"name\": \"self_attested_thing\"\n        }\n      },\n      \"requested_predicates\": {\n        \"0_age_GE_uuid\": {\n          \"name\": \"birthdate_dateint\",\n          \"p_type\": \"&lt;=\",\n          \"p_value\": 20030101,\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n</code></pre> <p>(Note that the birthdate requested above is used as an \"age proof\", the calculation is something like <code>now() - years(18)</code>, and the presented birthdate must be on or before this date.  You can see the calculation in action in the <code>faber.py</code> demo code.)</p> <p>Notice that the proof request is using a predicate to check if Alice is older than 18 without asking for her age. Not sure what this has to do with her education level! Click <code>Execute</code> and cross your fingers. If the request fails check your JSON!</p> Show me a screenshot - send proof request"},{"location":"demo/AriesOpenAPIDemo/#alice-responding-to-the-proof-request","title":"Alice - Responding to the Proof Request","text":"<p>As before, Alice receives a webhook event from her agent telling her she has received a Proof Request. In our scenario, the ACA-Py instance automatically selects a matching credential and responds with a Proof.</p> Show me Alice's event activity <p>In a real scenario, for example if Alice had a mobile agent on her smartphone, the agent would prompt Alice whether she wanted to respond or not.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-verifying-the-proof","title":"Faber - Verifying the Proof","text":"<p>Note that in the response, the state is <code>request-sent</code>. That is because when the HTTP response was generated (immediately after sending the request), Alice's agent had not yet responded to the request. We\u2019ll have to do another request to verify the presentation worked. Copy the value of the <code>pres_ex_id</code> field from the event in the Faber terminal and use it in executing the <code>GET /present-proof-2.0/records/{pres_ex_id}</code> endpoint. That should return a result showing the <code>state</code> as <code>done</code> and <code>verified</code> as <code>true</code>. Proof positive!</p> <p>You can see some of Faber's activity below:</p> Show me Faber's event activity"},{"location":"demo/AriesOpenAPIDemo/#present-proof-notes","title":"Present Proof Notes","text":"<p>As with the issue credential process, the agents handled some of the presentation steps without bothering the controller. In this case, Alice's agent processed the presentation request automatically through its handler for the <code>present_proof_v2_0</code> event, and her wallet contained exactly one credential that satisfied the presentation-request from the Faber agent. Similarly, the Faber agent's handler for the event responds automatically and so on receipt of the presentation, it verified the presentation and updated the status accordingly.</p>"},{"location":"demo/AriesOpenAPIDemo/#bonus-points_1","title":"Bonus Points","text":"<p>If you would like to perform all of the proof request/response steps manually, you can call all of the individual <code>/present-proof-2.0</code> messages.</p> <p>The following table lists endpoints that you need to call (\"REST service\") and callbacks that your agent will receive (\"callback\") that you need to respond to. See the detailed API docs.</p> Protocol Step Faber (Verifier) Alice (Holder/Prover) Notes Send Proof Request <code>POST /present-proof-2.0/send-request</code> REST service Receive Proof Request /present_proof_v2_0 callback (webhook) Find Credentials <code>GET /present-proof-2.0/records/{pres_ex_id}/credentials</code> REST service Select Credentials application or user function Send Proof <code>POST /present-proof-2.0/records/{pres_ex_id}/send-presentation</code> REST service Receive Proof /present_proof_v2_0 callback (webhook) Validate Proof <code>POST /present-proof-2.0/records/{pres_ex_id}/verify-presentation</code> REST service Save Proof application data"},{"location":"demo/AriesOpenAPIDemo/#conclusion","title":"Conclusion","text":"<p>That\u2019s the OpenAPI-based tutorial. Feel free to play with the API and learn how it works. More importantly, as you implement a controller, use the OpenAPI user interface to test out the calls you will be using as you go. The list of API calls is grouped by protocol and if you are familiar with the protocols (Aries RFCs) the API call names should be pretty obvious.</p> <p>One limitation of you being the controller is that you don't see the events from the agent that a controller program sees. For example, you, as Alice's agent, are not notified when Faber initiates the sending of a Credential. Some of those things show up in the terminal as messages, but others you just have to know have happened based on a successful API call.</p>"},{"location":"demo/AriesPostmanDemo/","title":"Aries Postman Demo","text":"<p>In these demos we will use Postman as our controller client.</p>"},{"location":"demo/AriesPostmanDemo/#contents","title":"Contents","text":"<ul> <li>Getting Started</li> <li>Installing Postman</li> <li>Creating a workspace</li> <li>Importing the environment</li> <li>Importing the collections</li> <li>Postman basics</li> <li>Experimenting with the vc-api endpoints</li> <li>Register new dids</li> <li>Issue credentials</li> <li>Store and retrieve credentials</li> <li>Verify credentials</li> <li>Prove a presentation</li> <li>Verify a presentation</li> </ul>"},{"location":"demo/AriesPostmanDemo/#getting-started","title":"Getting Started","text":"<p>Welcome to the Postman demo. This is an addition to the available OpenAPI demo, providing a set of collections to test and demonstrate various aca-py functionalities.</p>"},{"location":"demo/AriesPostmanDemo/#installing-postman","title":"Installing Postman","text":"<p>Download, install and launch postman.</p>"},{"location":"demo/AriesPostmanDemo/#creating-a-workspace","title":"Creating a workspace","text":"<p>Create a new postman workspace labeled \"acapy-demo\".</p>"},{"location":"demo/AriesPostmanDemo/#importing-the-environment","title":"Importing the environment","text":"<p>In the environment tab from the left, click the import button. You can paste this link which is the environment file in the ACA-Py repository.</p> <p>Make sure you have the environment set as your active environment.</p>"},{"location":"demo/AriesPostmanDemo/#importing-the-collections","title":"Importing the collections","text":"<p>In the collections tab from the left, click the import button.</p> <p>The following collections are available:</p> <ul> <li>vc-api</li> </ul>"},{"location":"demo/AriesPostmanDemo/#postman-basics","title":"Postman basics","text":"<p>Once you are setup, you will be ready to run postman requests. The order of the request is important, since some values are saved dynamically as environment variables for subsequent calls.</p> <p>You have your environment where you define variables to be accessed by your collections.</p> <p>Each collection consists of a series of requests which can be configured independently.</p>"},{"location":"demo/AriesPostmanDemo/#experimenting-with-the-vc-api-endpoints","title":"Experimenting with the vc-api endpoints","text":"<p>Make sure you have a demo agent available. You can use the following command to deploy one:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --bg\n</code></pre> <p>When running for the first time, please allow some time for the images to build.</p>"},{"location":"demo/AriesPostmanDemo/#register-new-dids","title":"Register new dids","text":"<p>The first 2 requests for this collection will create 2 did:keys. We will use those in subsequent calls to issue <code>Ed25519Signature2020</code> and <code>BbsBlsSignature2020</code> credentials. Run the 2 did creation requests. These requests will use the <code>/wallet/did/create</code> endpoint.</p>"},{"location":"demo/AriesPostmanDemo/#issue-credentials","title":"Issue credentials","text":"<p>For issuing, you must input a w3c compliant json-ld credential and issuance options in your request body. The issuer field must be a registered did from the agent's wallet. The suite will be derived from the did method.</p> <pre><code>{\n    \"credential\":   { \n        \"@context\": [\n            \"https://www.w3.org/2018/credentials/v1\"\n        ],\n        \"type\": [\n            \"VerifiableCredential\"\n        ],\n        \"issuer\": \"did:example:123\",\n        \"issuanceDate\": \"2022-05-01T00:00:00Z\",\n        \"credentialSubject\": {\n            \"id\": \"did:example:123\"\n        }\n    },\n    \"options\": {}\n}\n</code></pre> <p>Some examples have been pre-configured in the collection. Run the requests and inspect the results. Experiment with different credentials.</p>"},{"location":"demo/AriesPostmanDemo/#store-and-retrieve-credentials","title":"Store and retrieve credentials","text":"<p>Your last issued credential will be stored as an environment variable for subsequent calls, such as storing, verifying and including in a presentation.</p> <p>Try running the store credential request, then retrieve the credential with the list and fetch requests. Try going back and forth between the issuance endpoints and the storage endpoints to store multiple different credentials.</p>"},{"location":"demo/AriesPostmanDemo/#verify-credentials","title":"Verify credentials","text":"<p>You can verify your last issued credential with this endpoint or any issued credential you provide to it.</p>"},{"location":"demo/AriesPostmanDemo/#prove-a-presentation","title":"Prove a presentation","text":"<p>Proving a presentation is an action where a holder will prove ownership of a credential by signing or demonstrating authority over the document.</p>"},{"location":"demo/AriesPostmanDemo/#verify-a-presentation","title":"Verify a presentation","text":"<p>The final request is to verify a presentation.</p>"},{"location":"demo/Endorser/","title":"Endorser Demo","text":"<p>There are two ways to run the alice/faber demo with endorser support enabled.</p>"},{"location":"demo/Endorser/#run-faber-as-an-author-with-a-dedicated-endorser-agent","title":"Run Faber as an Author, with a dedicated Endorser agent","text":"<p>This approach runs Faber as an un-privileged agent, and starts a dedicated Endorser Agent in a sub-process (an instance of ACA-Py) to endorse Faber's transactions.</p> <p>Start a VON Network instance and a Tails server:</p> <ul> <li>Following the Building and Starting section of the VON Network Tutorial to get ledger started. You can leave off the <code>--logs</code> option if you want to use the same terminal for running both VON Network and the Tails server. When you are finished with VON Network, follow the Stopping And Removing a VON Network instructions.</li> <li>Run an AnonCreds revocation registry tails server in order to support revocation by following the instructions in the Alice gets a Phone demo.</li> </ul> <p>Start up Faber as Author (note the tails file size override, to allow testing of the revocation registry roll-over):</p> <pre><code>TAILS_FILE_COUNT=5 ./run_demo faber --endorser-role author --revocation\n</code></pre> <p>Start up Alice as normal:</p> <pre><code>./run_demo alice\n</code></pre> <p>You can run all of Faber's functions as normal - if you watch the console you will see that all ledger operations go through the endorser workflow.</p> <p>If you issue more than 5 credentials, you will see Faber creating a new revocation registry (encluding endorser operations).</p>"},{"location":"demo/Endorser/#run-alice-as-an-author-and-faber-as-an-endorser","title":"Run Alice as an Author and Faber as an Endorser","text":"<p>This approach sets up the endorser roles to allow manual testing using the agents' swagger pages:</p> <ul> <li>Faber runs as an Endorser (all of Faber's functions - issue credential, request proof, etc.) run normally, since Faber has ledger write access</li> <li>Alice starts up with a DID aith Author privileges (no ledger write access) and Faber is setup as Alice's Endorser</li> </ul> <p>Start a VON Network and a Tails server using the instructions above.</p> <p>Start up Faber as Endorser:</p> <pre><code>TAILS_FILE_COUNT=5 ./run_demo faber --endorser-role endorser --revocation\n</code></pre> <p>Start up Alice as Author:</p> <pre><code>TAILS_FILE_COUNT=5 ./run_demo alice --endorser-role author --revocation\n</code></pre> <p>Copy the invitation from Faber to Alice to complete the connection.</p> <p>Then in the Alice shell, select option \"D\" and copy Faber's DID (it is the DID displayed on faber agent startup).</p> <p>This starts up the ACA-Py agents with the endorser role set (via the new command-line args) and sets up the connection between the 2 agents with appropriate configuration.</p> <p>Then, in the Alice swagger page you can create a schema and cred def, and all the endorser steps will happen automatically.  You don't need to specify a connection id or explicitly request endorsement (ACA-Py does it all automatically based on the startup args).</p> <p>If you check the endorser transaction records in either Alice or Faber you can see that the endorser protocol executes automatically and the appropriate endorsements were endorsed before writing the transactions to the ledger.</p>"},{"location":"demo/ReusingAConnection/","title":"Reusing a Connection","text":"<p>The Aries RFC 0434 Out of Band protocol enables the concept of reusing a connection such that when using RFC 0023 DID Exchange to establish a connection with an agent with which you already have a connection, you can reuse the existing connection instead of creating a new one. This is something you couldn't do a with the older RFC 0160 Connection Protocol that we used in the early days of Aries. It was a pain, and made for a lousy user experience, as on every visit to an existing contact, the invitee got a new connection.</p> <p>The requirements on your invitations (such as in the example below) are:</p> <ul> <li>The invitation <code>services</code> item MUST be a resolvable DID.</li> <li>Or alternatively, the invitation <code>services</code> item MUST NOT be an <code>inline</code> service.</li> <li>The DID in the invitation <code>services</code> item is the same one in every invitation.</li> </ul> <p>Example invitation:</p> <pre><code>{\n    \"@type\": \"https://didcomm.org/out-of-band/1.1/invitation\",\n    \"@id\": \"77489d63-caff-41fe-a4c1-ec7e2ff00695\",\n    \"label\": \"faber.agent\",\n    \"handshake_protocols\": [\n        \"https://didcomm.org/didexchange/1.0\"\n    ],\n    \"services\": [\n        \"did:sov:4JiUsoK85pVkkB1bAPzFaP\"\n    ]\n}\n</code></pre> <p>Here's the flow that demonstrates where reuse helps. For simplicity, we'll use the terms \"Issuer\" and \"Wallet\" in this example, but it applies to any connection between any two agents (the inviter and the invitee) that establish connections with one another.</p> <ul> <li>The Wallet user is using a browser on the Issuers website and gets to the   point where they are going to be offered a credential. As part of that flow,   they are presented with a QR code that they scan with their wallet app.</li> <li>The QR contains an RFC 0434 Out of Band invitation to connect that the   Wallet processes as the invitee.</li> <li>The Wallet uses the information in the invitation to send an RFC 0023 DID Exchange request   DIDComm message back to the Issuer to initiate establishing a connection.</li> <li>The Issuer responds back to the <code>request</code> with a <code>response</code> message, and the   connection is established.</li> <li>Later, the Wallet user returns to the Issuer's website, and does something   (perhaps starts the process to get another credential) that results in the   same QR code being displayed, and again the users scans the QR code with their   Wallet app.</li> <li>The Wallet recognizes (based on the DID in the <code>services</code> item in the   invitation -- see example below) that it already has a connection to the   Issuer, so instead of sending a DID Exchange <code>request</code> message back to the   Issuer, they send an RFC 0434 Out of Band reuse DIDComm message, and both   parties know to use the existing connection.</li> <li>Had the Wallet used the DID Exchange <code>request</code> message, a new connection     would have been established.</li> </ul> <p>The RFC 0434 Out of Band protocol requirement enables <code>reuse</code> message by the invitee (the Wallet in the flow above) is that the <code>service</code> in the invitation MUST be a resolvable DID that is the same in all of the invitations. In the example invitation above, the DID is a <code>did:sov</code> DID that is resolvable on a public Hyperledger Indy network. The DID could also be a Peer DID of types 2 or 4, which encode the entire DIDDoc contents into the DID identifier (thus they are \"resolvable DIDs\"). What cannot be used is either the old \"unqualified\" DIDs that were commonly used in Aries prior to 2024, and Peer DID type 1. Both of those have DID types include both an identifier and a DIDDoc in the <code>services</code> item of the Out of Band invitation. As noted in the Out of Band specification, <code>reuse</code> cannot be used with such DID types even if the contents are the same.</p> <p>Example invitation:</p> <pre><code>{\n    \"@type\": \"https://didcomm.org/out-of-band/1.1/invitation\",\n    \"@id\": \"77489d63-caff-41fe-a4c1-ec7e2ff00695\",\n    \"label\": \"faber.agent\",\n    \"handshake_protocols\": [\n        \"https://didcomm.org/didexchange/1.0\"\n    ],\n    \"services\": [\n        \"did:sov:4JiUsoK85pVkkB1bAPzFaP\"\n    ]\n}\n</code></pre> <p>The use of conenction reuse can be demonstrated with the Alice / Faber demos as follows. We assume you have already somewhat familiar with your options for running the Alice Faber Demo (e.g. locally or in a browser). Follow those instruction up to the point where you are about to start the Faber and Alice agents.</p> <ol> <li>On a command line, run Faber with these parameters: <code>./run_demo faber    --reuse-connection --events</code>.</li> <li>On a second command line, run Alice as normal, perhaps with the <code>events</code>    option: <code>./run_demo alice --events</code></li> <li>Copy the invitation from the Faber terminal and paste it into the Alice    terminal at the prompt.</li> <li>Verify that the connection was established.</li> <li>If you want, go to the Alice OpenAPI screen (port <code>8031</code>, path       <code>api/docs</code>), and then use the <code>GET Connections</code> to see that Alice has one       connection to Faber.</li> <li>In the Alice terminal, type <code>4</code> to get a prompt for a new connection, and    paste the same invitation as in Step 3 (above).</li> <li>Note from the webhook events in the Faber terminal that the <code>reuse</code> message    is received from Alice, and as a result, no new connection was created.</li> <li>Execute again the <code>GET Connections</code> endpoint on the Alice OpenAPI screen       to confirm that there is still just one established connection.</li> <li>In the Faber terminal, type <code>4</code> to get a new invitation, copy the invitation,    in the Alice terminal, type <code>4</code> to get prompted for an invitation, and paste    in the new invitation from Faber. Again, the <code>reuse</code> webhook event will be    visible in the Faber terminal.</li> <li>Execute again the <code>GET Connections</code> endpoint on the Alice OpenAPI screen       to confirm that there is still just one established connection.</li> <li>Notice that in the invitations in Step 3 and 7 both have the same DID in       the <code>services</code>.</li> <li>Try running the demo again without the <code>--reuse-connection</code> parameter and    compare the <code>services</code> value in the new invitation vs. what was generated in    Steps 3 and 7. It is not a DID, but rather a one time use, inline DIDDoc    item.</li> </ol> <p>While in the demo Faber uses in the invitation the same DID they publish as an issuer (and uses in creating the schema and Cred Def for the demo), Faber could use any resolvable (not inline) DID, including DID Peer types 2 or 4 DIDs, as long as the DID is the same in every invitation. It is the fact that the DID is always the same that tells the invitee that they can reuse an existing connection.</p> <p>Note that the invitation does NOT have to be a multi-use invitation for reuse to be useful, as long as the other requirements (at the top of this document) are met.</p>"},{"location":"deploying/AnonCredsWalletType/","title":"AnonCreds-RS Support","text":"<p>A new wallet type has been added to Aca-Py to support the new anoncreds-rs library:</p> <pre><code>--wallet-type askar-anoncreds\n</code></pre> <p>When Aca-Py is run with this wallet type it will run with an Askar format wallet (and askar libraries) but will use <code>anoncreds-rs</code> instead of <code>credx</code>.</p> <p>There is a new package under <code>aries_cloudagent/anoncreds</code> with code that supports the new library.</p> <p>There are new endpoints (under <code>/anoncreds</code>) for creating a Schema and Credential Definition.  However the new anoncreds code is integrated into the existing Credential and Presentation endpoints (V2.0 endpoints only).</p> <p>Within the protocols, there are new <code>handler</code> libraries to support the new <code>anoncreds</code> format (these are in parallel to the existing <code>indy</code> libraries).</p> <p>The existing <code>indy</code> code are in:</p> <pre><code>aries_cloudagent/protocols/issue_credential/v2_0/formats/indy/handler.py\naries_cloudagent/protocols/indy/anoncreds/pres_exch_handler.py\naries_cloudagent/protocols/present_proof/v2_0/formats/indy/handler.py\n</code></pre> <p>The new <code>anoncreds</code> code is in:</p> <pre><code>aries_cloudagent/protocols/issue_credential/v2_0/formats/anoncreds/handler.py\naries_cloudagent/protocols/present_proof/anoncreds/pres_exch_handler.py\naries_cloudagent/protocols/present_proof/v2_0/formats/anoncreds/handler.py\n</code></pre> <p>The Indy handler checks to see if the wallet type is <code>askar-anoncreds</code> and if so delegates the calls to the anoncreds handler, for example:</p> <pre><code>        # Temporary shim while the new anoncreds library integration is in progress\n        wallet_type = profile.settings.get_value(\"wallet.type\")\n        if wallet_type == \"askar-anoncreds\":\n            self.anoncreds_handler = AnonCredsPresExchangeHandler(profile)\n</code></pre> <p>... and then:</p> <pre><code>        # Temporary shim while the new anoncreds library integration is in progress\n        if self.anoncreds_handler:\n            return self.anoncreds_handler.get_format_identifier(message_type)\n</code></pre> <p>To run the alice/faber demo using the new anoncreds library, start the demo with:</p> <pre><code>--wallet-type askar-anoncreds\n</code></pre> <p>There are no anoncreds-specific integration tests, for the new anoncreds functionality the agents within the integration tests are started with:</p> <pre><code>--wallet-type askar-anoncreds\n</code></pre> <p>Everything should just work!!!</p> <p>Theoretically ATH should work with anoncreds as well, by setting the wallet type (see https://github.com/hyperledger/aries-agent-test-harness#extra-backchannel-specific-parameters).</p>"},{"location":"deploying/AnonCredsWalletType/#revocation-new-in-anoncreds","title":"Revocation (new in anoncreds)","text":"<p>The changes are significant.  Notably:</p> <ul> <li>the old way was that from Indy you got the timestamp of the RevRegEntry used, accumulator and the \"deltas\" -- list of revoked and list of unrevoked credentials for a given range.  I'm not exactly sure what was passed to the AnonCreds library code for building the presentation.</li> <li>In the new way, the AnonCreds library expects the identifier for the revregentry used (aka the timestamp), the accumulator, and the full state (0s and 1s) of the revocation status of all credentials in the registry.</li> <li>The conversion from delta to full state must be handled in the Indy resolver -- not in the \"generic\" ACA-Py code, since the other ledgers automagically provide the full state. In fact, we're likely to update Indy VDR to always provide the full state.  The \"common\" (post resolver) code should get back from the resolver the full state.</li> </ul> <p>The Tails File changes are minimal -- nothing about the file itself changed.  What changed:</p> <ul> <li>the tails-file-server can be published to WITHOUT knowing the ID of the RevRegEntry, since that is not known when the tails file is generated/published.  See: https://github.com/bcgov/indy-tails-server/pull/53 -- basically, by publishing based on the hash.</li> <li>The tails-file is not needed by the issuer after generation. It used to be needed for issuing and revoking credentials. Those are now done without the tails file. See: https://github.com/hyperledger/aries-cloudagent-python/pull/2302/files. That code is already in Main, so you should have it.</li> </ul>"},{"location":"deploying/AnonCredsWalletType/#outstanding-work","title":"Outstanding work","text":"<ul> <li>revocation notifications (not sure if they're included in <code>anoncreds-rs</code> updates, haven't tested them ...)</li> <li>revocation support - complete the revocation implementation (support for unhappy path scenarios)</li> <li> <p>testing - various scenarios like mediation, multitenancy etc.</p> </li> <li> <p>unit tests (in the new anoncreds package) (see https://github.com/hyperledger/aries-cloudagent-python/pull/2596/commits/229ffbba209aff0ea7def5bad6556d93057f3c2a)</p> </li> <li>unit tests (review and possibly update unit tests for the credential and presentation integration)</li> <li>endorsement (not implemented with new anoncreds code)</li> <li>wallet upgrade (askar to askar-anoncreds)</li> <li>update V1.0 versions of the Credential and Presentation endpoints to use anoncreds</li> <li>any other anoncreds issues - https://github.com/hyperledger/aries-cloudagent-python/issues?q=is%3Aopen+is%3Aissue+label%3AAnonCreds</li> </ul>"},{"location":"deploying/AnonCredsWalletType/#retiring-old-indy-and-askar-credx-code","title":"Retiring old Indy and Askar (credx) Code","text":"<p>The main changes for the Credential and Presentation support are in the following two files:</p> <pre><code>aries_cloudagent/protocols/issue_credential/v2_0/messages/cred_format.py\naries_cloudagent/protocols/present_proof/v2_0/messages/pres_format.py\n</code></pre> <p>The <code>INDY</code> handler just need to be re-pointed to the new anoncreds handler, and then all the old Indy code can be retired.</p> <p>The new code is already in place (in comments).  For example for the Credential handler:</p> <pre><code>        To make the switch from indy to anoncreds replace the above with the following\n        INDY = FormatSpec(\n            \"hlindy/\",\n            DeferLoad(\n                \"aries_cloudagent.protocols.present_proof.v2_0\"\n                \".formats.anoncreds.handler.AnonCredsPresExchangeHandler\"\n            ),\n        )\n</code></pre> <p>There is a bunch of duplicated code, i.e. the new anoncreds code was added either as new classes (as above) or as new methods within an existing class.</p> <p>Some new methods were added within the Ledger class.</p> <p>New unit tests were added - in some cases as methods within existing test classes, and in some cases as new classes (whichever was easiest at the time).</p>"},{"location":"deploying/ContainerImagesAndGithubActions/","title":"Container Images and Github Actions","text":"<p>Aries Cloud Agent - Python is most frequently deployed using containers. From the first release of ACA-Py up through 0.7.4, much of the community has built their Aries stack using the container images graciously provided by BC Gov and hosted through their <code>bcgovimages</code> docker hub account. These images have been critical to the adoption of not only ACA-Py but also Hyperledger Aries and SSI more generally.</p> <p>Recognizing how critical these images are to the success of ACA-Py and consistent with Hyperledger's commitment to open collaboration, container images are now built and published directly from the Aries Cloud Agent - Python project repository and made available through the Github Packages Container Registry.</p>"},{"location":"deploying/ContainerImagesAndGithubActions/#image","title":"Image","text":"<p>This project builds and publishes the <code>ghcr.io/hyperledger/aries-cloudagent-python</code> image. Multiple variants are available; see Tags.</p>"},{"location":"deploying/ContainerImagesAndGithubActions/#tags","title":"Tags","text":"<p>ACA-Py is a foundation for building decentralized identity applications; to this end, there are multiple variants of ACA-Py built to suit the needs of a variety of environments and workflows. There are currently two main variants:</p> <ul> <li>\"Standard\" - The default configuration of ACA-Py, including:</li> <li>Aries Askar for secure storage</li> <li>Indy VDR for Indy ledger communication</li> <li>Indy Shared Libraries for AnonCreds</li> <li>\"Indy\" - The legacy configuration of ACA-Py, including:</li> <li>Indy SDK Wallet for secure storage</li> <li>Indy SDK Ledger for Indy ledger communication</li> <li>Indy SDK for AnonCreds</li> </ul> <p>These two image variants are largely distinguished by providers for Indy Network and AnonCreds support. The Standard variant is recommended for new projects. Migration from an Indy based image (whether the new Indy image variant or the original BC Gov images) to the Standard image is outside of the scope of this document.</p> <p>The ACA-Py images built by this project are tagged to indicate which of the above variants it is. Other tags may also be generated for use by developers.</p> <p>Below is a table of all generated images and their tags:</p> Tag Variant Example Description py3.9-X.Y.Z Standard py3.9-0.7.4 Standard image variant built on Python 3.9 for ACA-Py version X.Y.Z py3.10-X.Y.Z Standard py3.10-0.7.4 Standard image variant built on Python 3.10 for ACA-Py version X.Y.Z py3.9-indy-A.B.C-X.Y.Z Indy py3.9-indy-1.16.0-0.7.4 Standard image variant built on Python 3.9 for ACA-Py version X.Y.Z and Indy SDK Version A.B.C py3.10-indy-A.B.C-X.Y.Z Indy py3.10-indy-1.16.0-0.7.4 Standard image variant built on Python 3.10 for ACA-Py version X.Y.Z and Indy SDK Version A.B.C"},{"location":"deploying/ContainerImagesAndGithubActions/#image-comparison","title":"Image Comparison","text":"<p>There are several key differences that should be noted between the two image variants and between the BC Gov ACA-Py images.</p> <ul> <li>Standard Image</li> <li>Based on slim variant of Debian</li> <li>Does NOT include <code>libindy</code></li> <li>Default user is <code>aries</code></li> <li>Uses container's system python environment rather than <code>pyenv</code></li> <li>Askar and Indy Shared libraries are installed as dependencies of ACA-Py through pip from pre-compiled binaries included in the python wrappers</li> <li>Built from repo contents</li> <li>Indy Image</li> <li>Based on slim variant of Debian</li> <li>Built from multi-stage build step (<code>indy-base</code> in the Dockerfile) which includes Indy dependencies; this could be replaced with an explicit <code>indy-python</code> image from the Indy SDK repo</li> <li>Includes <code>libindy</code> but does NOT include the Indy CLI</li> <li>Default user is <code>indy</code></li> <li>Uses container's system python environment rather than <code>pyenv</code></li> <li>Askar and Indy Shared libraries are installed as dependencies of ACA-Py through pip from pre-compiled binaries included in the python wrappers</li> <li>Built from repo contents</li> <li>Includes Indy postgres storage plugin</li> <li><code>bcgovimages/aries-cloudagent</code></li> <li>(Usually) based on Ubuntu</li> <li>Based on <code>von-image</code></li> <li>Default user is <code>indy</code></li> <li>Includes <code>libindy</code> and Indy CLI</li> <li>Uses <code>pyenv</code></li> <li>Askar and Indy Shared libraries built from source</li> <li>Built from ACA-Py python package uploaded to PyPI</li> <li>Includes Indy postgres storage plugin</li> </ul>"},{"location":"deploying/ContainerImagesAndGithubActions/#github-actions","title":"Github Actions","text":"<ul> <li>Tests (<code>.github/workflows/tests.yml</code>) - A reusable workflow that runs tests   for the Standard ACA-Py variant for a given python version.</li> <li>Tests (Indy) (<code>.github/workflows/tests-indy.yml</code>) - A reusable workflow that   runs tests for the Indy ACA-Py variant for a given python and indy version.</li> <li>PR Tests (<code>.github/workflows/pr-tests.yml</code>) - Run on pull requests; runs tests   for the Standard and Indy ACA-Py variants for a \"default\" python version.   Check this workflow for the current default python and Indy versions in use.</li> <li>Nightly Tests (<code>.github/workflows/nightly-tests.yml</code>) - Run nightly; runs   tests for the Standard and Indy ACA-Py variants for all currently supported   python versions. Check this workflow for the set of currently supported   versions and Indy version(s) in use.</li> <li>Publish (<code>.github/workflows/publish.yml</code>) - Run on new release published or   when manually triggered; builds and pushes the Standard ACA-Py variant to the   Github Container Registry.</li> <li>Publish (Indy) (<code>.github/workflows/publish-indy.yml</code>) - Run on new release   published or when manually triggered; builds and pushes the Indy ACA-Py   variant to the Github Container Registry.</li> <li>Integration Tests (<code>.github/workflows/integrationtests.yml</code>) - Run on pull   requests (to the hyperledger fork only); runs BDD integration tests.</li> <li>Black Format (<code>.github/workflows/blackformat.yml</code>) - Run on pull requests;   checks formatting of files modified by the PR.</li> <li>CodeQL (<code>.github/workflows/codeql.yml</code>) - Run on pull requests; performs   CodeQL analysis.</li> <li>Python Publish (<code>.github/workflows/pythonpublish.yml</code>) - Run on release   created; publishes ACA-Py python package to PyPI.</li> <li>PIP Audit (<code>.github/workflows/pipaudit.yml</code>) - Run when manually triggered;   performs pip audit.</li> </ul>"},{"location":"deploying/Databases/","title":"Databases","text":"<p>Your wallet stores secret keys, connections and other information. You have different choices to store this information. The wallet supports 2 different databases to store data, SQLite and PostgreSQL.</p>"},{"location":"deploying/Databases/#sqlite","title":"SQLite","text":"<p>If the wallet is configured the default way in eg. demo-args.yaml, without explicit wallet-storage, a sqlite database file is used.</p> <pre><code># demo-args.yaml\nwallet-type: indy\nwallet-name: wallet\nwallet-key: wallet-password\n</code></pre> <p>For this configuration, a folder called wallet will be created which contains a file called <code>sqlite.db</code>.</p>"},{"location":"deploying/Databases/#postgresql","title":"PostgreSQL","text":"<p>The wallet can be configured to use PostgreSQL as storage.</p> <pre><code># demo-args.yaml\nwallet-type: indy\nwallet-name: wallet\nwallet-key: wallet-password\n\nwallet-storage-type: postgres_storage\nwallet-storage-config: \"{\\\"url\\\":\\\"db:5432\\\",\\\"wallet_scheme\\\":\\\"DatabasePerWallet\\\"}\"\nwallet-storage-creds: \"{\\\"account\\\":\\\"postgres\\\",\\\"password\\\":\\\"mysecretpassword\\\",\\\"admin_account\\\":\\\"postgres\\\",\\\"admin_password\\\":\\\"mysecretpassword\\\"}\"\n</code></pre> <p>In this case the hostname for the database is <code>db</code> on port 5432.</p> <p>A docker-compose file could look like this:</p> <pre><code># docker-compose.yml\nversion: '3'\nservices:\n  # acapy ...\n  # database\n  db:\n    image: postgres:10\n    environment:\n      POSTGRES_PASSWORD: mysecretpassword\n      POSTGRES_USER: postgres\n      POSTGRES_DB: postgres\n    ports:\n      - \"5432:5432\"\n</code></pre>"},{"location":"deploying/IndySDKtoAskarMigration/","title":"Migrating from Indy SDK to Askar","text":"<p>The document summarizes why the Indy SDK is being deprecated, it's replacement (Aries Askar and the \"shared components\"), how to use Aries Askar in a new ACA-Py deployment, and the migration process for an ACA-Py instance that is already deployed using the Indy SDK.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#the-time-has-come-archiving-indy-sdk","title":"The Time Has Come! Archiving Indy SDK","text":"<p>Yes, it\u2019s time. Indy SDK needs to be archived! In this article we\u2019ll explain why this change is needed, why Aries Askar is a faster, better replacement, and how to transition your Indy SDK-based ACA-Py deployment to Askar as soon as possible.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#history-of-indy-sdk","title":"History of Indy SDK","text":"<p>Indy SDK has been the basis of Hyperledger Indy and Hyperledger Aries clients accessing Indy networks for a long time. It has done an excellent job at exactly what you might imagine: being the SDK that enables clients to leverage the capabilities of a Hyperledger Indy ledger.</p> <p>Its continued use has been all the more remarkable given that the last published release of the Indy SDK was in 2020. This speaks to the quality of the implementation \u2014 it just kept getting used, doing what it was supposed to do, and without major bugs, vulnerabilities or demands for new features.</p> <p>However, the architecture of Indy SDK has critical bottlenecks. Most notably, as load increases, Indy SDK performance drops. And with Indy-based ecosystems flourishing and loads exponentially increasing, this means the Aries/Indy community needed to make a change.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#aries-askar-and-the-shared-components","title":"Aries Askar and the Shared Components","text":"<p>The replacement for the Indy SDK is a set of four components, each replacing a part of Indy SDK. (In retrospect, Indy SDK ought to have been split up this way from the start.)</p> <p>The components are:</p> <ol> <li>Aries Askar: the replacement for the \u201cindy-wallet\u201d part of Indy SDK.    Askar is a key management service, handling the creation and use of private    keys managed by Aries agents. It\u2019s also the secure storage for DIDs,    verifiable credentials, and data used by issuers of verifiable credentials    for signing. As the Aries moniker indicates, Askar is suitable for use with    any Aries agent, and for managing any keys, whether for use with Indy or any    other Verifiable Data Registry (VDR).</li> <li>Indy VDR: the interface to publishing to and retrieving data from    Hyperledger Indy networks. Indy VDR is scoped at the appropriate level for    any client application using Hyperledger Indy networks.</li> <li>CredX: a Rust implementation of AnonCreds that evolved from the Indy    SDK implementation. CredX is within the indy-shared-rs repository. It has    significant performance enhancements over the version in the Indy SDK,    particularly for Issuers.</li> <li>Hyperledger AnonCreds: a newer implementation of AnonCreds that is    \u201cledger-agnostic\u201d \u2014 it can be used with Hyperledger Indy and any other    suitable verifiable data registry.</li> </ol> <p>In ACA-Py, we are currently using CredX, but will be moving to Hyperledger AnonCreds soon.</p> <p>If you\u2019re involved in the community, you\u2019ll know we\u2019ve been planning this replacement for almost three years. The first release of the Aries Askar and related components was in 2021. At the end of 2022 there was a concerted effort to eliminate the Indy SDK by creating migration scripts, and removing the Indy SDK from various tools in the community (the Indy CLI, the Indy Test Automation pipeline, and so on). This step is to finish the task.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#performance","title":"Performance","text":"<p>What\u2019s the performance and stability of the replacement? In short, it\u2019s dramatically better. Overall Aries Askar performance is faster, and as the load increases the performance remains constant. Combined with added flexibility and modularization, the community is very positive about the change.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#new-aca-py-deployments","title":"New ACA-Py Deployments","text":"<p>If you are new to ACA-Py, the instructions are easy. Use Aries Askar and the shared components from the start. To do that, simply make sure that you are using the <code>--wallet-type askar</code> configuration parameter. You will automatically be using all of the shared components.</p> <p>As of release 0.9.0, you will get a deprecation warning when you start ACA-Py with the Indy SDK. Switch to Aries Askar to eliminate that warning.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#migrating-existing-indy-sdk-aca-py-deployments-to-askar","title":"Migrating Existing Indy SDK ACA-Py Deployments to Askar","text":"<p>If you have an existing deployment, in changing the <code>--wallet-type</code> configuration setting, your database must be migrated from the Indy SDK format to Aries Askar format. In order to facilitate the migration, an Indy SDK to Askar migration script has been published in the aries-acapy-tools repository. There is lots of information in that repository about the migration tool and how to use it. The following is a summary of the steps you will have to perform. Of course, all deployments are a little (or a lot!) different, and your exact steps will be dependent on where and how you have deployed ACA-Py.</p> <p>Note that in these steps you will have to take your ACA-Py instance offline, so scheduling the maintenance must be a part of your migration plan. You will also want to script the entire process so that downtime and risk of manual mistakes are minimized.</p> <p>We hope that you have one or two test environments (e.g., Dev and Test) to run through these steps before upgrading your production deployment. As well, it is good if you can make a copy of your production database and test the migration on the real (copy) database before the actual upgrade.</p> <ul> <li>Prepare a way to run the Askar Upgrade script from the aries-acapy-tools   repository. For example, you might want to prepare a container that you can   run in the same environment that you run ACA-Py (e.g., within Kubernetes or   OpenShift).</li> <li>Shutdown your ACA-Py instance.</li> <li>Backup the existing wallet using the usual tools you have for backing up the   database.</li> <li>If you are running in a cloud native environment such as Kubernetes, deploy   the Askar Upgrade container, and as needed, update the network policies to   allow the Askar Upgrade container to connect with the wallet database</li> <li>Run the <code>askar-upgrade</code> script. For example:</li> </ul> <pre><code>askar-upgrade \\\n  --strategy dbpw \\\n  --uri postgres://&lt;username&gt;:&lt;password&gt;@&lt;hostname&gt;:&lt;port&gt;/&lt;dbname&gt; \\\n  --wallet-name &lt;wallet name&gt; \\\n  --wallet-key &lt;wallet key&gt;\n</code></pre> <ul> <li>Switch the ACA-Py instance's <code>--wallet-type</code> configuration setting to <code>askar</code></li> <li>Start up the ACA-Py instances.</li> <li>Trouble? Restore the initial database and revert the <code>--wallet-type</code> change     to rollback to the pre-migration state.</li> <li>Check the data.</li> <li>Test the deployment.</li> </ul> <p>It is very important that the Askar Upgrade script has direct access to the database. In our very first upgrade attempt, we ran the Upgrade Askar script from a container running outside of our container orchestration platform (OpenShift) using port forwarding. The script ran EXTREMELY slowly, taking literally hours to run before we finally stopped it. Once we ran the script inside the OpenShift environment, the script ran (for the same database) in about 7 minutes. The entire app downtime was less than 20 minutes.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#questions","title":"Questions?","text":"<p>If you have questions, comments, or suggestions about the upgrade process, please use the Aries Cloud Agent Python channel on Hyperledger Discord, or submit a GitHub issue to the ACA-Py repository.</p>"},{"location":"deploying/Poetry/","title":"Poetry Cheat Sheet for Developers","text":""},{"location":"deploying/Poetry/#introduction-to-poetry","title":"Introduction to Poetry","text":"<p>Poetry is a dependency management and packaging tool for Python that aims to simplify and enhance the development process. It offers features for managing dependencies, virtual environments, and building and publishing Python packages.</p>"},{"location":"deploying/Poetry/#virtual-environments-with-poetry","title":"Virtual Environments with Poetry","text":"<p>Poetry manages virtual environments for your projects to ensure clean and isolated development environments.</p>"},{"location":"deploying/Poetry/#creating-a-virtual-environment","title":"Creating a Virtual Environment","text":"<pre><code>poetry install\n</code></pre>"},{"location":"deploying/Poetry/#activating-the-virtual-environment","title":"Activating the Virtual Environment","text":"<pre><code>poetry shell\n</code></pre> <p>Alternatively you can source the environment settings in the current shell</p> <pre><code>source $(poetry env info --path)/bin/activate\n</code></pre> <p>for powershell users this would be</p> <pre><code>(&amp; ((poetry env info --path) + \"\\Scripts\\activate.ps1\")\n</code></pre>"},{"location":"deploying/Poetry/#deactivating-the-virtual-environment","title":"Deactivating the Virtual Environment","text":"<p>When using <code>poetry shell</code></p> <pre><code>exit\n</code></pre> <p>When using the <code>activate</code> script</p> <pre><code>deactivate\n</code></pre>"},{"location":"deploying/Poetry/#dependency-management","title":"Dependency Management","text":"<p>Poetry uses the <code>pyproject.toml</code> file to manage dependencies. Add new dependencies to this file and update existing ones as needed.</p>"},{"location":"deploying/Poetry/#adding-a-dependency","title":"Adding a Dependency","text":"<pre><code>poetry add package-name\n</code></pre>"},{"location":"deploying/Poetry/#adding-a-development-dependency","title":"Adding a Development Dependency","text":"<pre><code>poetry add --dev package-name\n</code></pre>"},{"location":"deploying/Poetry/#removing-a-dependency","title":"Removing a Dependency","text":"<pre><code>poetry remove package-name\n</code></pre>"},{"location":"deploying/Poetry/#updating-dependencies","title":"Updating Dependencies","text":"<pre><code>poetry update\n</code></pre>"},{"location":"deploying/Poetry/#running-tasks-with-poetry","title":"Running Tasks with Poetry","text":"<p>Poetry provides a way to run scripts and commands without activating the virtual environment explicitly.</p>"},{"location":"deploying/Poetry/#running-a-command","title":"Running a Command","text":"<pre><code>poetry run command-name\n</code></pre>"},{"location":"deploying/Poetry/#running-a-script","title":"Running a Script","text":"<pre><code>poetry run python script.py\n</code></pre>"},{"location":"deploying/Poetry/#building-and-publishing-with-poetry","title":"Building and Publishing with Poetry","text":"<p>Poetry streamlines the process of building and publishing Python packages.</p>"},{"location":"deploying/Poetry/#building-the-package","title":"Building the Package","text":"<pre><code>poetry build\n</code></pre>"},{"location":"deploying/Poetry/#publishing-the-package","title":"Publishing the Package","text":"<pre><code>poetry publish\n</code></pre>"},{"location":"deploying/Poetry/#using-extras","title":"Using Extras","text":"<p>Extras allow you to specify additional dependencies based on project requirements.</p>"},{"location":"deploying/Poetry/#installing-with-extras","title":"Installing with Extras","text":"<pre><code>poetry install -E extras-name\n</code></pre> <p>for example</p> <pre><code>poetry install -E \"askar bbs indy\"\n</code></pre>"},{"location":"deploying/Poetry/#managing-development-dependencies","title":"Managing Development Dependencies","text":"<p>Development dependencies are useful for tasks like testing, linting, and documentation generation.</p>"},{"location":"deploying/Poetry/#installing-development-dependencies","title":"Installing Development Dependencies","text":"<pre><code>poetry install --dev\n</code></pre>"},{"location":"deploying/Poetry/#additional-resources","title":"Additional Resources","text":"<ul> <li>Poetry Documentation</li> <li>PyPI: The Python Package Index</li> </ul>"},{"location":"deploying/RedisPlugins/","title":"ACA-Py Redis Plugins","text":""},{"location":"deploying/RedisPlugins/#aries-acapy-plugin-redis-events-redis_queue","title":"aries-acapy-plugin-redis-events <code>redis_queue</code>","text":"<p>It provides a mechanism to persists both inbound and outbound messages using redis, deliver messages and webhooks, and dispatch events.</p> <p>More details can be found here.</p>"},{"location":"deploying/RedisPlugins/#redis-queue-configuration-yaml","title":"Redis Queue configuration <code>yaml</code>","text":"<pre><code>redis_queue:\n  connection: \n    connection_url: \"redis://default:test1234@172.28.0.103:6379\"\n\n  ### For Inbound ###\n  inbound:\n    acapy_inbound_topic: \"acapy_inbound\"\n    acapy_direct_resp_topic: \"acapy_inbound_direct_resp\"\n\n  ### For Outbound ###\n  outbound:\n    acapy_outbound_topic: \"acapy_outbound\"\n    mediator_mode: false\n\n  ### For Event ###\n  event:\n    event_topic_maps:\n      ^acapy::webhook::(.*)$: acapy-webhook-$wallet_id\n      ^acapy::record::([^:]*)::([^:]*)$: acapy-record-with-state-$wallet_id\n      ^acapy::record::([^:])?: acapy-record-$wallet_id\n      acapy::basicmessage::received: acapy-basicmessage-received\n      acapy::problem_report: acapy-problem_report\n      acapy::ping::received: acapy-ping-received\n      acapy::ping::response_received: acapy-ping-response_received\n      acapy::actionmenu::received: acapy-actionmenu-received\n      acapy::actionmenu::get-active-menu: acapy-actionmenu-get-active-menu\n      acapy::actionmenu::perform-menu-action: acapy-actionmenu-perform-menu-action\n      acapy::keylist::updated: acapy-keylist-updated\n      acapy::revocation-notification::received: acapy-revocation-notification-received\n      acapy::revocation-notification-v2::received: acapy-revocation-notification-v2-received\n      acapy::forward::received: acapy-forward-received\n    event_webhook_topic_maps:\n      acapy::basicmessage::received: basicmessages\n      acapy::problem_report: problem_report\n      acapy::ping::received: ping\n      acapy::ping::response_received: ping\n      acapy::actionmenu::received: actionmenu\n      acapy::actionmenu::get-active-menu: get-active-menu\n      acapy::actionmenu::perform-menu-action: perform-menu-action\n      acapy::keylist::updated: keylist\n    deliver_webhook: true\n</code></pre> <ul> <li><code>redis_queue.connection.connection_url</code>: This is required and is expected in <code>redis://{username}:{password}@{host}:{port}</code> format.</li> <li><code>redis_queue.inbound.acapy_inbound_topic</code>: This is the topic prefix for the inbound message queues. Recipient key of the message are also included in the complete topic name. The final topic will be in the following format <code>acapy_inbound_{recip_key}</code></li> <li><code>redis_queue.inbound.acapy_direct_resp_topic</code>: Queue topic name for direct responses to inbound message.</li> <li><code>redis_queue.outbound.acapy_outbound_topic</code>: Queue topic name for the outbound messages. Used by Deliverer service to deliver the payloads to specified endpoint.</li> <li><code>redis_queue.outbound.mediator_mode</code>: Set to true, if using Redis as a http bridge when setting up a mediator agent. By default, it is set to false.</li> <li><code>event.event_topic_maps</code>: Event topic map</li> <li><code>event.event_webhook_topic_maps</code>: Event to webhook topic map</li> <li><code>event.deliver_webhook</code>: When set to true, this will deliver webhooks to endpoints specified in <code>admin.webhook_urls</code>. By default, set to true.</li> </ul>"},{"location":"deploying/RedisPlugins/#redis-plugin-usage","title":"Redis Plugin Usage","text":""},{"location":"deploying/RedisPlugins/#redis-plugin-with-docker","title":"Redis Plugin With Docker","text":"<p>Running the plugin with docker is simple. An example docker-compose.yml file is available which launches both ACA-Py with redis and an accompanying Redis cluster.</p> <pre><code>docker-compose up --build -d\n</code></pre> <p>More details can be found here.</p>"},{"location":"deploying/RedisPlugins/#without-docker","title":"Without Docker","text":"<p>Installation</p> <pre><code>pip install git+https://github.com/bcgov/aries-acapy-plugin-redis-events.git\n</code></pre> <p>Startup ACA-Py with <code>redis_queue</code> plugin loaded</p> <pre><code>docker network create --subnet=172.28.0.0/24 `network_name`\nexport REDIS_PASSWORD=\" ... As specified in redis_cluster.conf ... \"\nexport NETWORK_NAME=\"`network_name`\"\naca-py start \\\n    --plugin redis_queue.v1_0.events \\\n    --plugin-config plugins-config.yaml \\\n    -it redis_queue.v1_0.inbound redis 0 -ot redis_queue.v1_0.outbound\n    # ... the remainder of your startup arguments\n</code></pre> <p>Regardless of the options above, you will need to startup <code>deliverer</code> and <code>relay</code>/<code>mediator</code> service as a bridge to receive inbound messages. Consider the following to build your <code>docker-compose</code> file which should also start up your redis cluster:</p> <ul> <li> <p>Relay + Deliverer</p> <pre><code>relay:\n    image: redis-relay\n    build:\n        context: ..\n        dockerfile: redis_relay/Dockerfile\n    ports:\n        - 7001:7001\n        - 80:80\n    environment:\n        - REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379\n        - TOPIC_PREFIX=acapy\n        - STATUS_ENDPOINT_HOST=0.0.0.0\n        - STATUS_ENDPOINT_PORT=7001\n        - STATUS_ENDPOINT_API_KEY=test_api_key_1\n        - INBOUND_TRANSPORT_CONFIG=[[\"http\", \"0.0.0.0\", \"80\"]]\n        - TUNNEL_ENDPOINT=http://relay-tunnel:4040\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n    depends_on:\n        - redis-cluster\n        - relay-tunnel\n    networks:\n        - acapy_default\ndeliverer:\n    image: redis-deliverer\n    build:\n        context: ..\n        dockerfile: redis_deliverer/Dockerfile\n    ports:\n        - 7002:7002\n    environment:\n        - REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379\n        - TOPIC_PREFIX=acapy\n        - STATUS_ENDPOINT_HOST=0.0.0.0\n        - STATUS_ENDPOINT_PORT=7002\n        - STATUS_ENDPOINT_API_KEY=test_api_key_2\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n    depends_on:\n        - redis-cluster\n    networks:\n        - acapy_default\n</code></pre> </li> <li> <p>Mediator + Deliverer</p> <pre><code>mediator:\n    image: acapy-redis-queue\n    build:\n        context: ..\n        dockerfile: docker/Dockerfile\n    ports:\n        - 3002:3001\n    depends_on:\n        - deliverer\n    volumes:\n        - ./configs:/home/indy/configs:z\n        - ./acapy-endpoint.sh:/home/indy/acapy-endpoint.sh:z\n    environment:\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n        - TUNNEL_ENDPOINT=http://mediator-tunnel:4040\n    networks:\n        - acapy_default\n    entrypoint: /bin/sh -c '/wait &amp;&amp; ./acapy-endpoint.sh poetry run aca-py \"$$@\"' --\n    command: start --arg-file ./configs/mediator.yml\n\ndeliverer:\n    image: redis-deliverer\n    build:\n        context: ..\n        dockerfile: redis_deliverer/Dockerfile\n    depends_on:\n        - redis-cluster\n    ports:\n        - 7002:7002\n    environment:\n        - REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379\n        - TOPIC_PREFIX=acapy\n        - STATUS_ENDPOINT_HOST=0.0.0.0\n        - STATUS_ENDPOINT_PORT=7002\n        - STATUS_ENDPOINT_API_KEY=test_api_key_2\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n    networks:\n        - acapy_default\n</code></pre> </li> </ul> <p>Both relay and mediator demos are also available.</p>"},{"location":"deploying/RedisPlugins/#aries-acapy-cache-redis-redis_cache","title":"aries-acapy-cache-redis <code>redis_cache</code>","text":"<p>ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose of this plugin is to allow ACA-Py to use Redis as the storage medium for it's caching needs.</p> <p>More details can be found here.</p>"},{"location":"deploying/RedisPlugins/#redis-cache-plugin-configuration-yaml","title":"Redis Cache Plugin configuration <code>yaml</code>","text":"<pre><code>redis_cache:\n  connection: \"redis://default:test1234@172.28.0.103:6379\"\n  max_connection: 50\n  credentials:\n    username: \"default\"\n    password: \"test1234\"\n  ssl:\n    cacerts: ./ca.crt\n</code></pre> <ul> <li><code>redis_cache.connection</code>: This is required and is expected in <code>redis://{username}:{password}@{host}:{port}</code> format.</li> <li><code>redis_cache.max_connection</code>: Maximum number of redis pool connections. Default: 50</li> <li><code>redis_cache.credentials.username</code>: Redis instance username</li> <li><code>redis_cache.credentials.password</code>: Redis instance password</li> <li><code>redis_cache.ssl.cacerts</code></li> </ul>"},{"location":"deploying/RedisPlugins/#redis-cache-usage","title":"Redis Cache Usage","text":""},{"location":"deploying/RedisPlugins/#redis-cache-using-docker","title":"Redis Cache Using Docker","text":"<ul> <li> <p>Running the plugin with docker is simple and straight-forward. There is an example docker-compose.yml file in the root of the project that launches both ACA-Py and an accompanying Redis instance. Running it is as simple as:</p> <pre><code>docker-compose up --build -d\n</code></pre> </li> <li> <p>To launch ACA-Py with an accompanying redis cluster of 6 nodes (3 primaries and 3 replicas), please refer to example docker-compose.cluster.yml and run the following:</p> <p>Note: Cluster requires external docker network with specified subnet</p> <pre><code>docker network create --subnet=172.28.0.0/24 `network_name`\nexport REDIS_PASSWORD=\" ... As specified in redis_cluster.conf ... \"\nexport NETWORK_NAME=\"`network_name`\"\ndocker-compose -f docker-compose.cluster.yml up --build -d\n</code></pre> </li> </ul>"},{"location":"deploying/RedisPlugins/#redis-cache-without-docker","title":"Redis Cache Without Docker","text":"<p>Installation</p> <pre><code>pip install git+https://github.com/Indicio-tech/aries-acapy-cache-redis.git\n</code></pre> <p>Startup ACA-Py with <code>redis_cache</code> plugin loaded</p> <pre><code>aca-py start \\\n    --plugin acapy_cache_redis.v0_1 \\\n    --plugin-config plugins-config.yaml \\\n    # ... the remainder of your startup arguments\n</code></pre> <p>or</p> <pre><code>aca-py start \\\n    --plugin acapy_cache_redis.v0_1 \\\n    --plugin-config-value \"redis_cache.connection=redis://redis-host:6379/0\" \\\n    --plugin-config-value \"redis_cache.max_connections=90\" \\\n    --plugin-config-value \"redis_cache.credentials.username=username\" \\\n    --plugin-config-value \"redis_cache.credentials.password=password\" \\\n    # ... the remainder of your startup arguments\n</code></pre>"},{"location":"deploying/RedisPlugins/#redis-cluster","title":"Redis Cluster","text":"<p>If you startup a redis cluster and an ACA-Py agent loaded with either <code>redis_queue</code> or <code>redis_cache</code> plugin or both, then during the initialization of the plugin, it will bind an instance of <code>redis.asyncio.RedisCluster</code> (onto the <code>root_profile</code>). Other plugin will have access to this redis client for it's functioning. This is done for efficiency and to avoid duplication of resources.</p>"},{"location":"deploying/UpgradingACA-Py/","title":"Upgrading ACA-Py Data","text":"<p>Some releases of ACA-Py may be improved by, or even require, an upgrade when moving to a new version. Such changes are documented in the CHANGELOG.md, and those with ACA-Py deployments should take note of those upgrades. This document summarizes the upgrade system in ACA-Py.</p>"},{"location":"deploying/UpgradingACA-Py/#version-information-and-automatic-upgrades","title":"Version Information and Automatic Upgrades","text":"<p>The file version.py contains the current version of a running instance of ACA-Py. In addition, a record is made in the ACA-Py secure storage (database) about the \"most recently upgraded\" version. When deploying a new version of ACA-Py, the version.py value will be higher than the version in secure storage. When that happens, an upgrade is executed, and on successful completion, the version is updated in secure storage to match what is in version.py.</p> <p>Upgrades are defined in the Upgrade Definition YML file. For a given version listed in the follow, the corresponding entry is what actions are required when upgrading from a previous version. If a version is not listed in the file, there is no upgrade defined for that version from its immediate predecessor version.</p> <p>Once an upgrade is identified as needed, the process is:</p> <ul> <li>Collect (if any) the actions to be taken to get from the version recorded in secure storage to the current version.py</li> <li>Execute the actions from oldest to newest.</li> <li>If the same action is collected more than once (e.g., \"Resave the Connection Records\" is defined for two different versions), perform the action only once.</li> <li>Store the current ACA-Py version (from version.py) in the secure storage   database.</li> </ul>"},{"location":"deploying/UpgradingACA-Py/#forced-offline-upgrades","title":"Forced Offline Upgrades","text":"<p>In some cases, it may be necessary to do an offline upgrade, where ACA-Py is taken off line temporarily, the database upgraded explicitly, and then ACA-Py re-deployed as normal. As yet, we do not have any use cases for this, but those deploying ACA-Py should be aware of this possibility. For example, we may at some point need an upgrade that MUST NOT be executed by more than one ACA-Py instance. In that case, a \"normal\" upgrade could be dangerous for deployments on container orchestration platforms like Kubernetes.</p> <p>If the Maintainers of ACA-Py recognize a case where ACA-Py must be upgraded while offline, a new Upgrade feature will be added that will prevent the \"auto upgrade\" process from executing. See Issue 2201 and Pull Request 2204 for the status of that feature.</p> <p>Those deploying ACA-Py upgrades for production installations (forced offline or not) should check in each CHANGELOG.md release entry about what upgrades (if any) will be run when upgrading to that version, and consider how they want those upgrades to run in their ACA-Py installation. In most cases, simply deploying the new version should be OK. If the number of records to be upgraded is high (such as a \"resave connections\" upgrade to a deployment with many, many connections), you may want to do a test upgrade offline first, to see if there is likely to be a service disruption during the upgrade. Plan accordingly!</p>"},{"location":"deploying/UpgradingACA-Py/#tagged-upgrades","title":"Tagged upgrades","text":"<p>Upgrades are defined in the Upgrade Definition YML file, in addition to specifying upgrade actions by version they can also be specified by named tags. Unlike version based upgrades where all applicable version based actions will be performed based upon sorted order of versions, with named tags only actions corresponding to provided tags will be performed. Note: <code>--force-upgrade</code> is required when running name tags based upgrade (i.e. providing <code>--named-tag</code>).</p> <p>Tags are specified in YML file as below:</p> <pre><code>fix_issue_rev_reg:\n  fix_issue_rev_reg_records: true\n</code></pre> <p>Example:</p> <pre><code> ./scripts/run_docker upgrade --force-upgrade --named-tag fix_issue_rev_reg\n\n# In case, running multiple tags [say test1 &amp; test2]:\n ./scripts/run_docker upgrade --force-upgrade --named-tag test1 --named-tag test2\n</code></pre>"},{"location":"deploying/UpgradingACA-Py/#subwallet-upgrades","title":"Subwallet upgrades","text":"<p>With multitenant enabled, there is a subwallet associated with each tenant profile, so there is a need to upgrade those sub wallets in addition to the base wallet associated with root profile.</p> <p>There are 2 options to perform such upgrades:</p> <ul> <li><code>--upgrade-all-subwallets</code></li> </ul> <p>This will apply the upgrade steps to all sub wallets (tenant profiles) and the base wallet (root profiles).</p> <ul> <li><code>--upgrade-subwallet</code></li> </ul> <p>This will apply the upgrade steps to specified sub wallets (identified by wallet id) and the base wallet.</p> <p>Note: multiple specifications allowed</p>"},{"location":"deploying/UpgradingACA-Py/#exceptions","title":"Exceptions","text":"<p>There are a couple of upgrade exception conditions to consider, as outlined in the following sections.</p>"},{"location":"deploying/UpgradingACA-Py/#no-version-in-secure-storage","title":"No version in secure storage","text":"<p>Versions prior to ACA-Py 0.8.1 did not automatically populate the secure storage \"version\" record. That only occurred if an upgrade was explicitly executed. As of ACA-Py 0.8.1, the version record is added immediately after the secure storage database is created. If you are upgrading to ACA-Py 0.8.1 or later, and there is no version record in the secure storage, ACA-Py will assume you are running version 0.7.5, and execute the upgrades from version 0.7.5 to the current version. The choice of 0.7.5 as the default is safe because the same upgrades will be run on any version of ACA-Py up to and including 0.7.5, as can be seen in the Upgrade Definition YML file. Thus, even if you are really upgrading from (for example) 0.6.2, the same upgrades are needed as from 0.7.5 to a post-0.8.1 version.</p>"},{"location":"deploying/UpgradingACA-Py/#forcing-an-upgrade","title":"Forcing an upgrade","text":"<p>If you need to force an upgrade from a given version of ACA-Py, a pair of configuration options can be used together. If you specify \"<code>--from-version &lt;ver&gt;</code>\" and \"<code>--force-upgrade</code>\", the <code>--from-version</code> version will override what is found (or not) in secure storage, and the upgrade will be from that version to the current one. For example, if you have \"0.8.1\" in your \"secure storage\" version, and you know that the upgrade for version 0.8.1 has not been executed, you can use the parameters <code>--from-version v0.7.5 --force-upgrade</code> to force the upgrade on next starting an ACA-Py instance. However, given the few upgrades defined prior to version 0.8.1, and the \"no version in secure storage\" handling, it is unlikely this capability will ever be needed. We expect to deprecate and remove these options in future (post-0.8.1) ACA-Py versions.</p>"},{"location":"deploying/deploymentModel/","title":"Deployment Model","text":""},{"location":"deploying/deploymentModel/#aries-cloud-agent-python-aca-py-deployment-model","title":"Aries Cloud Agent-Python (ACA-Py) - Deployment Model","text":"<p>This document is a \"concept of operations\" for an instance of an Aries cloud agent deployed from the primary artifact (a PyPi package) produced by this repo. In such a deployment there are always two components - a configured agent itself, and a controller that injects into that agent the business rules for the particular agent instance (see diagram).</p> <p></p> <p>The deployed agent messages with other agents via DIDComm protocols, and as events associated with those messages occur, sends webhook HTTP notifications to the controller. The agent also exposes for the controller's exclusive use an HTTP API covering all of the administrative handlers for those events. The controller receives the notifications from the agent, decides (with business rules - possible by asking a person using a UI) how to respond to the event and calls back to the agent via the HTTP API. Of course, the controller may also initiate events (e.g. messaging another agent) by calling that same API.</p> <p>The following is an example of the interactions involved in creating a connection using the DIDComm \"Establish Connection\" protocol. The controller requests from the agent (via the administrative API) a connection invitation from the agent, and receives one back. The controller provides it to another agent (perhaps by displaying it in a QR code). Shortly after, the agent receives a DIDComm \"Connection Request\" message. The agent, sends it to the controller. The controller decides to accept the connection and calls the API with instructions to the agent to send a \"Connection Response\" message to the other agent. Since the controller always wants to know with whom a connection has been created, the controller also sends instructions to the agent (via the API, of course) to send a request presentation message to the new connection. And so on... During the interactions, the agent is tracking the state of the connections, and the state of the protocol instances (threads). Likewise, the controller may also be retaining state - after all, it's an application that could do anything.</p> <p>Most developers will configure a \"black box\" instance of the ACA-Py. They need to know how it works, the DIDComm protocols it supports, the events it will generate and the administrative API it exposes. However, they don't need to drill into and maintain the ACA-Py code. Such developers will build controller applications (basically, traditional web apps) that at their simplest, use an HTTP interface to receive notification and send HTTP requests to the agent. It's the business logic implemented in, or accessed by the controller that gives the deployment its personality and role.</p> <p>Note: the ACA-Py agent is designed to be stateless, persisting connection and protocol state to storage (such as Postgres database). As such, agents can be deployed to support horizontal scaling as necessary. Controllers can also be implemented to support horizontal scaling.</p> <p>The sections below detail the internals of the ACA-Py and it's configurable elements, and the conceptual elements of a controller. There is no \"Aries controller\" repo to fork, as it is essentially just a web app. There are demos of using the elements in this repo, and several sample applications that you can use to get started on your on controller.</p>"},{"location":"deploying/deploymentModel/#aries-cloud-agent","title":"Aries Cloud Agent","text":"<p>Aries cloud agent implement services to manage the execution of DIDComm messaging protocols for interacting with other DIDComm agents, and exposes an administrative HTTP API that supports a controller to direct how the agent should respond to messaging events. The agent relies on the controller to provide the business rules for handling the messaging events, and to initiate the execution of new DIDComm protocol instances. The internals of an ACA-Py instance is diagramed below.</p> <p></p> <p>Instances of the Aries cloud agents are configured with the following sub-components:</p> <ul> <li>Transport Plugins - pluggable transport-specific message sender/receiver modules that interact with other agents. Messages outside the plugins are transport-agnostic JSON structures. Current modules include HTTP and WebSockets. In the future, we might add ZMQ, SMTP and so on.</li> <li>Conductor receives inbound messages from, and sends outbound messages to, the transport plugins. After internal processing, the conductor passes inbound messages to, and receives outbound messages from, the Dispatcher. In processing the messages, the conductor manages the message\u2019s protocol instance thread state, retrieving the state on inbound messages and saving the state on outbound messages. The conductor handles generic decorators in messages such as verifying and generating signatures on message data elements, internationalization and so on.</li> <li>Dispatcher handles the distribution of messages to the DIDComm protocol message handlers and the responses received. The dispatcher passes to the conductor the thread state to be persistance and message data (if any) to be sent out from the Aries cloud agent instance.</li> <li>DIDComm Protocols - implement the DIDComm protocols supported by the agent instance, including the state object for the protocol, the DIDComm message handlers and the admin message handlers. Protocols are bundled as Python modules and loaded for during the agent deployment. Each protocol contributes the admin messages for the protocol to the controller REST interface. The protocols implement a number of events that invoke the controller via webhooks so that controller\u2019s business logic can respond to the event.</li> <li>Controller REST API - a dynamically generated REST API (with a Swagger/OpenAPI user interface) based on the set of DIDComm protocols included in the agent deployment. The controller, activated via the webhooks from the protocol DIDComm message handlers, controls the Aries cloud agent by calling the REST API that invoke the protocol admin message handlers.</li> <li>Handler API - provides abstract interfaces to various handlers needed by the protocols and core Aries cloud agent components for accessing the secure storage (wallet), other storage, the ledger and so on. The API calls the handler implementations configured into the agent deployment.</li> <li>Handler Plugins - are the handler implementations called from the Handler API. The plugins may be internal to the Agent (in the same process space) or could be external (for example, in other processes/containers).</li> <li>Secure Storage Plugin - the Indy SDK is embedded in the Aries cloud agent and implements the default secure storage. An Aries cloud agent can be configured to use one of a number of indy-sdk storage implementations - in-memory, SQLite and Postgres at this time.</li> <li>Ledger Interface Plugin - In the current Aries cloud agent implementation, the Indy SDK provides an interface to an Indy-based public ledger for verifiable credential protocols. In future, ledger implementations (including those other than Indy) might be moved into the DIDComm protocol modules to be included as needed within a configured Aries cloud agent instance based on the DIDComm protocols used by the agent.</li> </ul>"},{"location":"deploying/deploymentModel/#controller","title":"Controller","text":"<p>A controller provides the personality of Aries cloud agent instance - the business logic (human, machine or rules driven) that drive the behaviour of the agent. The controller\u2019s \u201cBusiness Logic\u201d in a cloud agent could be built into the controller app, could be an integration back to an enterprise system, or even a user interface for an individual. In all cases, the business logic provide responses to agent events or initiates agent actions. A deployed controller talks to a single Aries cloud agent deployment and manages the configuration of that agent. Both can be configured and deployed to support horizontal scaling.</p> <p></p> <p>Generically, a controller is a web app invoked by HTTP webhook calls from its corresponding Aries cloud agent and invoking the DIDComm administration capabilities of the Aries cloud agent by calling the REST API exposed by that cloud agent. As well as responding to Aries cloud agent events, the controller initiates DIDComm protocol instances using the same REST API.</p> <p>The controller and Aries cloud agent deployment MUST secure the HTTP interface between the two components. The interface provides the same HTTP integration between services as modern apps found in any enterprise today, and must be correspondingly secured.</p> <p>A controller implements the following capabilities.</p> <ul> <li>Initiator - provides a mechanism to initiate new DIDComm protocol instances. The initiator invokes the REST API exposed by the Aries cloud agent to initiate the creation of a DIDComm protocol instance. For example, a permit-issuing service uses this mechanism to issue a Verifiable Credential associated with the issuance of a new permit.</li> <li>Responder - subscribes to and responds to events from the Aries cloud agent protocol message handlers, providing business-driven responses. The responder might respond immediately, or the event might cause a delay while the decision is determined, perhaps by sending the request to a person to decide. The controller may persist the event response state if the event is asynchronous - for example, when the event is passed to a person who may respond when they next use the web app.</li> <li>Configuration - manages the controller configuration data and the configuration of the Aries cloud agent.  Configuration in this context includes things like:</li> <li>Credentials and Proof Requests to be Issued/Verified (respectively) by the Aries cloud agent.</li> <li>The configuration of the webhook handler to which the responder subscribes.</li> </ul> <p>While there are several examples of controllers, there is no \u201ccookie cutter\u201d repository to fork and customize. A controller is just a web service that receives HTTP requests (webhooks) and sends HTTP messages to the Aries cloud agent it controls via the REST API exposed by that agent.</p>"},{"location":"deploying/deploymentModel/#deployment","title":"Deployment","text":"<p>The Aries cloud agent CI pipeline configured into the repository generates a PyPi package as an artifact. Implementers will generally have a controller repository, possibly copied from an existing controller instance, that has the code (business logic) for the controller and the configuration (transports, handlers, DIDComm protocols, etc.) for the Aries cloud agent instance. In the most common scenario, the Aries cloud agent and controller instances will be deployed based on the artifacts (e.g. container images) generated from that controller repository. With the simple HTTP-based interface between the controller and Aries cloud agent, both components can be horizontally scaled as needed, with a load balancer between the components. The configuration of the Aries cloud agent to use the Postgres wallet supports enterprise scale agent deployments.</p> <p>Current examples of deployed instances of Aries cloud agent and controllers include:</p> <ul> <li>indy-email-verification - a web app Controller that sends an email to a given email address with an embedded DIDComm invitation and on establishment of a connection, offers and provides the connected agent with an email control verifiable credential.</li> <li>iiwbook - a web app Controller that on creation of a DIDComm connection, requests a proof of email control, and then sends to the connection a verifiable credential proving attendance at IIW. In between the proof and issuance is a human approval step using a simple web-based UI that implements a request queue.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/","title":"Supporting AnonCreds in W3C VC/VP Formats in Aries Cloud Agent Python","text":"<p>This design proposes to extend the Aries Cloud Agent Python (ACA-PY) to support Hyperledger AnonCreds credentials and presentations in the W3C Verifiable Credentials (VC) and Verifiable Presentations (VP) Format. The aim is to transition from the legacy AnonCreds format specified in Aries-Legacy-Method to the W3C VC format.</p>"},{"location":"design/AnoncredsW3CCompatibility/#overview","title":"Overview","text":"<p>The pre-requisites for the work are:</p> <ul> <li>The availability of the AnonCreds RS library supporting the generation and processing of AnonCreds VCs in W3C VC format.</li> <li>The availability of the AnonCreds RS library supporting the generation and verification of AnonCreds VPs in W3C VP format.</li> <li>The availability of support in the AnonCreds RS Python Wrapper for the W3C VC/VP capabilities in AnonCreds RS.</li> <li>Agreement on the Aries Issue Credential v2.0 and Present Proof v2.0 protocol attachment formats to use when issuing AnonCreds W3C VC format credentials, and when presenting AnonCreds W3C VP format presentations.</li> <li>For issuing, use the (proposed) RFC 0809 VC-DI Attachments</li> <li>For presenting, use the RFC 0510 DIF Presentation Exchange Attachments</li> </ul> <p>As of 2024-01-15, these pre-requisites have been met.</p>"},{"location":"design/AnoncredsW3CCompatibility/#impacts-on-aca-py","title":"Impacts on ACA-Py","text":""},{"location":"design/AnoncredsW3CCompatibility/#issuer","title":"Issuer","text":"<p>Issuer support needs to be added for using the RFC 0809 VC-DI attachment format when sending Issue Credential v2.0 protocol<code>offer</code> and <code>issue</code> messages and when receiving <code>request</code> messages.</p> <p>Related notes:</p> <ul> <li>The Issue Credential v1.0 protocol will not be updated to support AnonCreds W3C VC format credentials.</li> <li>Once an instance of the Issue Credential v2.0 protocol is started using RFC 0809 VC-DI format attachments, subsequent messages in the protocol MUST use RFC 0809 VC-DI attachments.</li> <li>The ACA-Py maintainers are discussing the possibility of making pluggable the Issue Credential v2.0 and Present Proof v2.0 attachment formats, to simplify supporting additional formats, including RFC 0809 VC-DI.</li> </ul> <p>A mechanism must be defined such that an Issuer controller can use the ACA-Py Admin API to initiate the sending of an AnonCreds credential Offer using the RFC 0809 VC-DI attachment format.</p> <p>A credential's encoded attributes are not included in the issued AnonCreds W3C VC format credential. To be determined how that impacts the issuing process.</p>"},{"location":"design/AnoncredsW3CCompatibility/#verifier","title":"Verifier","text":"<p>A verifier wanting a W3C VP Format presentation will send the Present Proof v2.0 <code>request</code> message with an RFC 0510 DIF Presentation Exchange format attachment.</p> <p>If needed, the RFC 0510 DIF Presentation Exchange document will be clarified and possibly updated to enable its use for handling AnonCreds W3C VP format presentations.</p> <p>An AnonCreds W3C VP format presentation does not include the encoded revealed attributes, and the encoded values must be calculated as needed. To be determined where those would be needed.</p>"},{"location":"design/AnoncredsW3CCompatibility/#holder","title":"Holder","text":"<p>A holder must support RFC 0809 VC-DI attachments when receiving Issue Credential v2.0 <code>offer</code> and <code>issue</code> messages, and when sending <code>request</code> messages.</p> <p>On receiving an Issue Credential v2.0 <code>offer</code> message with a RFC 0809 VC-DI, the holder MUST respond using the RFC 0809 VC-DI on the subsequent <code>request</code> message.</p> <p>On receiving a credential from an issuer in an RFC 0809 VC-DI attachment, the holder must process and store the credential for subsequent use in presentations.</p> <ul> <li>The AnonCreds verifiable credential MUST support being used in both legacy AnonCreds and W3C VP format (DIF Presentation Exchange) presentations.</li> </ul> <p>On receiving an RFC 0510 DIF Presentation Exchange <code>request</code> message, a holder must include AnonCreds verifiable credentials in the search for credentials satisfying the request, and if found and selected for use, must construct the presentation using the RFC 0510 DIF Presentation Exchange presentation format, with an embedded AnonCreds W3C VP format presentation.</p>"},{"location":"design/AnoncredsW3CCompatibility/#issues-to-consider","title":"Issues to consider","text":"<ul> <li>If and how the W3C VC Format attachments for the Issue Credential V2.0 and Present Proof V2 Aries DIDComm Protocols should be used when using AnonCreds W3C VC Format credentials. Anticipated triggers:</li> <li>An Issuer Controller invokes the Admin API to trigger an Issue Credential v2.0 protocol instance such that the RFC 0809 VC-DI will be used.</li> <li>A Holder receives an Issue Credential v2.0 <code>offer</code> message with an RFC 0809 VC-DI attachment.</li> <li>A Verifier initiates a Present Proof v2.0 protocol instance with an RFC 0510 DIF Presentation Exchange that can be satisfied by AnonCreds VCs held by the holder.</li> <li>A Holder receives a present proof <code>request</code> message with an RFC 0510 DIF Presentation Exchange format attachment that can be satisfied with AnonCreds credentials held by the holder.<ul> <li>How are the <code>restrictions</code> and <code>revocation</code> data elements conveyed?</li> </ul> </li> <li>How AnonCreds W3C VC Format verifiable credentials are stored by the holder such that they will be discoverable when needed for creating verifiable presentations.</li> <li>How and when multiple signatures can/should be added to a W3C VC Format credential, enabling both AnonCreds and non-AnonCreds signatures on a single credential and their use in presentations. Completing a multi-signature controller is out of scope, however we want to consider and ensure the design is fundamentally compatible with multi-sig credentials.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#flow-chart","title":"Flow Chart","text":""},{"location":"design/AnoncredsW3CCompatibility/#key-questions","title":"Key Questions","text":""},{"location":"design/AnoncredsW3CCompatibility/#what-is-the-roadmap-for-delivery-what-will-we-build-first-then-second","title":"What is the roadmap for delivery? What will we build first, then second?","text":"<p>It appears that the issue and presentation sides can be approached independently, assuming that any stored AnonCreds VC can be used in an AnonCreds W3C VP format presentation.</p>"},{"location":"design/AnoncredsW3CCompatibility/#issue-credential","title":"Issue Credential","text":"<ol> <li>Update Admin API endpoints to initiate an Issue Credential v2.0 protocol to issue an AnonCreds credential in W3C VC format using RFC 0809 VC-DI format attachments.</li> <li>Add support for the RFC 0809 VC-DI message attachment formats.</li> <li>Should the attachment format be made pluggable as part of this? From the maintainers: If we did make it pluggable, this would be the point where that would take place. Since these values are hard coded, it is not pluggable currently, as noted. I've been dissatisfied with how this particular piece works for a while. I think making it pluggable, if done right, could help clean it up nicely. A plugin would then define their own implementation of V20CredFormatHandler. (@dbluhm)</li> <li>Update the v2.0 Issue Credential protocol handler to support a \"RFC 0809 VC-DI mode\" such that when a protocol instance starts with that format, it continues with it until completion, supporting issuing AnonCreds credentials in the process. This includes both the sending and receiving of all protocol message types.</li> </ol>"},{"location":"design/AnoncredsW3CCompatibility/#present-proof","title":"Present Proof","text":"<ol> <li>Adjust as needed the sending of a Present Proof request using the RFC 0510 DIF Presentation Exchange with support (to be defined) for requesting AnonCreds VCs.</li> <li>Adjust as needed the processing of a Present Proof <code>request</code> message with an RFC 0510 DIF Presentation Exchange attachment so that AnonCreds VCs can found and used in the subsequent response.</li> <li>AnonCreds VCs issued as legacy or W3C VC format credentials should be usable in AnonCreds W3C VP format presentations.</li> <li>Update the creation of an RFC 0510 DIF Presentation Exchange presentation submission to support the use of AnonCreds VCs as the source of the VPs.</li> <li>Update the verifier receipt of a Present Proof v2.0 <code>presentation</code> message with an RFC 0510 DIF Presentation Exchange containing AnonCreds W3C VP(s) derived from AnonCreds source VCs.</li> </ol>"},{"location":"design/AnoncredsW3CCompatibility/#what-are-the-functions-we-are-going-to-wrap","title":"What are the functions we are going to wrap?","text":"<p>After thoroughly reviewing upcoming changes from anoncreds-rs PR273, the classes or <code>AnoncredsObject</code> impacted by changes are as follows:</p> <p>W3CCredential</p> <ul> <li>class methods (<code>create</code>, <code>load</code>)</li> <li>instance methods (<code>process</code>, <code>to_legacy</code>, <code>add_non_anoncreds_integrity_proof</code>, <code>set_id</code>, <code>set_subject_id</code>, <code>add_context</code>, <code>add_type</code>)</li> <li>class properties (<code>schema_id</code>, <code>cred_def_id</code>, <code>rev_reg_id</code>, <code>rev_reg_index</code>)</li> <li>bindings functions (<code>create_w3c_credential</code>, <code>process_w3c_credential</code>, <code>_object_from_json</code>, <code>_object_get_attribute</code>, <code>w3c_credential_add_non_anoncreds_integrity_proof</code>, <code>w3c_credential_set_id</code>, <code>w3c_credential_set_subject_id</code>, <code>w3c_credential_add_context</code>, <code>w3c_credential_add_type</code>)</li> </ul> <p>W3CPresentation</p> <ul> <li>class methods (<code>create</code>, <code>load</code>)</li> <li>instance methods (<code>verify</code>)</li> <li>bindings functions (<code>create_w3c_presentation</code>, <code>_object_from_json</code>, <code>verify_w3c_presentation</code>)</li> </ul> <p>They will be added to __init__.py as additional exports of AnoncredsObject.</p> <p>We also have to consider which classes or anoncreds objects have been modified</p> <p>The classes modified according to the same PR mentioned above are:</p> <p>Credential</p> <ul> <li>added class methods (<code>from_w3c</code>)</li> <li>added instance methods (<code>to_w3c</code>)</li> <li>added bindings functions (<code>credential_from_w3c</code>, <code>credential_to_w3c</code>)</li> </ul> <p>PresentCredential</p> <ul> <li>modified instance methods (<code>_get_entry</code>, <code>add_attributes</code>, <code>add_predicates</code>)</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#creating-a-w3c-vc-credential-from-credential-definition-and-issuing-and-presenting-it-as-is","title":"Creating a W3C VC credential from credential definition, and issuing and presenting it as is","text":"<p>The issuance, presentation and verification of legacy anoncreds are implemented in this ./aries_cloudagent/anoncreds directory. Therefore, we will also start from there.</p> <p>Let us navigate these implementation examples through the respective processes of the concerning agents - Issuer and Holder as described in https://github.com/hyperledger/anoncreds-rs/blob/main/README.md. We will proceed through the following processes in comparison with the legacy anoncreds implementations while watching out for signature differences between the two. Looking at the /anoncreds/issuer.py file, from <code>AnonCredsIssuer</code> class:</p> <p>Create VC_DI Credential Offer</p> <p>According to this DI credential offer attachment format - didcomm/w3c-di-vc-offer@v0.1,</p> <ul> <li>binding_required</li> <li>binding_method</li> <li>credential_definition</li> </ul> <p>could be the parameters for <code>create_offer</code> method.</p> <p>Create VC_DI Credential</p> <p>NOTE: There has been some changes to encoding of attribute values for creating a credential, so we have to be adjust to the new changes.</p> <pre><code>async def create_credential(\n        self,\n        credential_offer: dict,\n        credential_request: dict,\n        credential_values: dict,\n    ) -&gt; str:\n...\n...\n  try:\n    credential = await asyncio.get_event_loop().run_in_executor(\n        None,\n        lambda: W3CCredential.create(\n            cred_def.raw_value,\n            cred_def_private.raw_value,\n            credential_offer,\n            credential_request,\n            raw_values,\n            None,\n            None,\n            None,\n            None,\n        ),\n    )\n...\n</code></pre> <p>Create VC_DI Credential Request</p> <pre><code>async def create_vc_di_credential_request(\n        self, credential_offer: dict, credential_definition: CredDef, holder_did: str\n    ) -&gt; Tuple[str, str]:\n...\n...\ntry:\n  secret = await self.get_master_secret()\n  (\n      cred_req,\n      cred_req_metadata,\n  ) = await asyncio.get_event_loop().run_in_executor(\n      None,\n      W3CCredentialRequest.create,\n      None,\n      holder_did,\n      credential_definition.to_native(),\n      secret,\n      AnonCredsHolder.MASTER_SECRET_ID,\n      credential_offer,\n  )\n...\n</code></pre> <p>Create VC_DI Credential Presentation</p> <pre><code>async def create_vc_di_presentation(\n        self,\n        presentation_request: dict,\n        requested_credentials: dict,\n        schemas: Dict[str, AnonCredsSchema],\n        credential_definitions: Dict[str, CredDef],\n        rev_states: dict = None,\n    ) -&gt; str:\n...\n...\n  try:\n    secret = await self.get_master_secret()\n    presentation = await asyncio.get_event_loop().run_in_executor(\n        None,\n        Presentation.create,\n        presentation_request,\n        present_creds,\n        self_attest,\n        secret,\n        {\n            schema_id: schema.to_native()\n            for schema_id, schema in schemas.items()\n        },\n        {\n            cred_def_id: cred_def.to_native()\n            for cred_def_id, cred_def in credential_definitions.items()\n        },\n    )\n...\n</code></pre>"},{"location":"design/AnoncredsW3CCompatibility/#converting-an-already-issued-legacy-anoncreds-to-vc_di-formatvice-versa","title":"Converting an already issued legacy anoncreds to VC_DI format(vice versa)","text":"<p>In this case, we can use <code>to_w3c</code> method of <code>Credential</code> class to convert from legacy to w3c and <code>to_legacy</code> method of <code>W3CCredential</code> class to convert from w3c to legacy.</p> <p>We could call <code>to_w3c</code> method like this:</p> <pre><code>vc_di_cred = Credential.to_w3c(cred_def)\n</code></pre> <p>and for <code>to_legacy</code>:</p> <pre><code>legacy_cred = W3CCredential.to_legacy()\n</code></pre> <p>We don't need to input any parameters to it as it in turn calls <code>Credential.from_w3c()</code> method under the hood.</p>"},{"location":"design/AnoncredsW3CCompatibility/#format-handler-for-issue_credential-v2_0-protocol","title":"Format Handler for Issue_credential V2_0 Protocol","text":"<p>Keeping in mind that we are trying to create anoncreds(not another type of VC) in w3c format, what if we add a protocol-level vc_di format support by adding a new format <code>VC_DI</code> in <code>./protocols/issue_credential/v2_0/messages/cred_format.py</code> -</p> <pre><code># /protocols/issue_credential/v2_0/messages/cred_format.py\n\nclass Format(Enum):\n    \u201c\u201d\u201dAttachment Format\u201d\u201d\u201d\n    INDY = FormatSpec(...)\n    LD_PROOF = FormatSpec(...)\n    VC_DI = FormatSpec(\n        \u201cvc_di/\u201d,\n        CredExRecordVCDI,\n        DeferLoad(\n            \u201caries_cloudagent.protocols.issue_credential.v2_0\u201d\n            \u201c.formats.vc_di.handler.AnonCredsW3CFormatHandler\u201d\n        ),\n    )\n</code></pre> <p>And create a new CredExRecordVCDI in reference to V20CredExRecordLDProof</p> <pre><code># /protocols/issue_credential/v2_0/models/detail/w3c.py\n\nclass CredExRecordW3C(BaseRecord):\n    \"\"\"Credential exchange W3C detail record.\"\"\"\n\n    class Meta:\n        \"\"\"CredExRecordW3C metadata.\"\"\"\n\n        schema_class = \"CredExRecordW3CSchema\"\n\n    RECORD_ID_NAME = \"cred_ex_w3c_id\"\n    RECORD_TYPE = \"w3c_cred_ex_v20\"\n    TAG_NAMES = {\"~cred_ex_id\"} if UNENCRYPTED_TAGS else {\"cred_ex_id\"}\n    RECORD_TOPIC = \"issue_credential_v2_0_w3c\"\n</code></pre> <p>Based on the proposed credential attachment format with the new Data Integrity proof in aries-rfcs 809 -</p> <pre><code>{\n  \"@id\": \"284d3996-ba85-45d9-964b-9fd5805517b6\",\n  \"@type\": \"https://didcomm.org/issue-credential/2.0/issue-credential\",\n  \"comment\": \"&lt;some comment&gt;\",\n  \"formats\": [\n    {\n      \"attach_id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n      \"format\": \"didcomm/w3c-di-vc@v0.1\"\n    }\n  ],\n  \"credentials~attach\": [\n    {\n      \"@id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n      \"mime-type\": \"application/ld+json\",\n      \"data\": {\n        \"base64\": \"ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0=\"\n      }\n    }\n  ]\n}\n</code></pre> <p>Assuming <code>VCDIDetail</code> and <code>VCDIOptions</code> are already in place, <code>VCDIDetailSchema</code> can be created like so:</p> <pre><code># /protocols/issue_credential/v2_0/formats/vc_di/models/cred_detail.py\n\nclass VCDIDetailSchema(BaseModelSchema):\n    \"\"\"VC_DI verifiable credential detail schema.\"\"\"\n\n    class Meta:\n        \"\"\"Accept parameter overload.\"\"\"\n\n        unknown = INCLUDE\n        model_class = VCDIDetail\n\n    credential = fields.Nested(\n        CredentialSchema(),\n        required=True,\n        metadata={\n            \"description\": \"Detail of the VC_DI Credential to be issued\",\n            \"example\": {\n                \"@id\": \"284d3996-ba85-45d9-964b-9fd5805517b6\",\n                \"@type\": \"https://didcomm.org/issue-credential/2.0/issue-credential\",\n                \"comment\": \"&lt;some comment&gt;\",\n                \"formats\": [\n                    {\n                        \"attach_id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n                        \"format\": \"didcomm/w3c-di-vc@v0.1\"\n                    }\n                ],\n                \"credentials~attach\": [\n                    {\n                        \"@id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n                        \"mime-type\": \"application/ld+json\",\n                        \"data\": {\n                            \"base64\": \"ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0=\"\n                        }\n                    }\n                ]\n            }\n        },\n    )\n</code></pre> <p>Then create w3c format handler with mapping like so:</p> <pre><code># /protocols/issue_credential/v2_0/formats/w3c/handler.py\n\nmapping = {\n            CRED_20_PROPOSAL: VCDIDetailSchema,\n            CRED_20_OFFER: VCDIDetailSchema,\n            CRED_20_REQUEST: VCDIDetailSchema,\n            CRED_20_ISSUE: VerifiableCredentialSchema,\n        }\n</code></pre> <p>Doing so would allow us to be more independent in defining the schema suited for anoncreds in w3c format and once the proposal protocol can handle the w3c format, probably the rest of the flow can be easily implemented by adding <code>vc_di</code> flag to the corresponding routes.</p>"},{"location":"design/AnoncredsW3CCompatibility/#admin-api-attachments","title":"Admin API Attachments","text":"<p>To make sure that once an endpoint has been called to trigger the <code>Issue Credential</code> flow in <code>0809 W3C_DI attachment formats</code> the subsequent endpoints also follow this format, we can keep track of this ATTACHMENT_FORMAT dictionary with the proposed <code>VC_DI</code> format.</p> <pre><code># Format specifications\nATTACHMENT_FORMAT = {\n    CRED_20_PROPOSAL: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred-filter@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc-detail@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di-detail@v2.0\",\n    },\n    CRED_20_OFFER: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred-abstract@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc-detail@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di-detail@v2.0\",\n    },\n    CRED_20_REQUEST: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred-req@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc-detail@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di-detail@v2.0\",\n    },\n    CRED_20_ISSUE: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di@v2.0\",\n    },\n}\n</code></pre> <p>And this _formats_filter function takes care of keeping the attachment formats uniform across the iteration of the flow. We can see this function gets called in:</p> <ul> <li>_create_free_offer function that gets called in the handler function of <code>/issue-credential-2.0/send-offer</code> route (in addition to other offer routes)</li> <li>credential_exchange_send_free_request handler function of <code>/issue-credential-2.0/send-request</code> route</li> <li>credential_exchange_create handler function of <code>/issue-credential-2.0/create</code> route</li> <li>credential_exchange_send handler function of <code>/issue-credential-2.0/send</code> route</li> </ul> <p>The same goes for ATTACHMENT_FORMAT of <code>Present Proof</code> flow. In this case, DIF Presentation Exchange formats in these test vectors that are influenced by RFC 0510 DIF Presentation Exchange will be implemented. Here, the _formats_attach function is the key for the same purpose above. It gets called in:</p> <ul> <li>present_proof_send_proposal handler function of <code>/present-proof-2.0/send-proposal</code> route</li> <li>present_proof_create_request handler function of <code>/present-proof-2.0/create-request</code> route</li> <li>present_proof_send_free_request handler function of <code>/present-proof-2.0/send-request</code> route</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#credential-exchange-admin-routes","title":"Credential Exchange Admin Routes","text":"<ul> <li>/issue-credential-2.0/create-offer</li> </ul> <p>This route indirectly calls <code>_formats_filters</code> function to create credential proposal, which is in turn used to create a credential offer in the filter format. The request body for this route might look like this:</p> <pre><code>{\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-issue\": true,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n            ...\n            ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/create</li> </ul> <p>This route indirectly calls <code>_format_result_with_details</code> function to generate a cred_ex_record in the specified format, which is then returned. The request body for this route might look like this:</p> <pre><code>{\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-remove\": true,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/send</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"connection_id\": &lt;connection_id&gt;,\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/send-offer</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"connection_id\": &lt;connection_id&gt;,\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-issue\": true,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"holder_did\": &lt;holder_did&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/send-request</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"connection_id\": &lt;connection_id&gt;,\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"holder_did\": &lt;holder_did&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre>"},{"location":"design/AnoncredsW3CCompatibility/#presentation-admin-routes","title":"Presentation Admin Routes","text":"<ul> <li>/present-proof-2.0/send-proposal</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    ...\n    ...\n    \"connection_id\": &lt;connection_id&gt;,\n    \"presentation_proposal\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-present\": true,\n    \"auto-remove\": true,\n    \"trace\": false\n}\n</code></pre> <ul> <li>/present-proof-2.0/create-request</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    ...\n    ...\n    \"connection_id\": &lt;connection_id&gt;,\n    \"presentation_proposal\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-verify\": true,\n    \"auto-remove\": true,\n    \"trace\": false\n}\n</code></pre> <ul> <li>/present-proof-2.0/send-request</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    ...\n    ...\n    \"connection_id\": &lt;connection_id&gt;,\n    \"presentation_proposal\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-verify\": true,\n    \"auto-remove\": true,\n    \"trace\": false\n}\n</code></pre> <ul> <li>/present-proof-2.0/records/{pres_ex_id}/send-presentation</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"presentation_definition\": &lt;presentation_definition_schema&gt;,\n    \"auto_remove\": true,\n    \"dif\": {\n        issuer_id: \"&lt;issuer_id&gt;\",\n        record_ids: {\n            \"&lt;input descriptor id_1&gt;\": [\"&lt;record id_1&gt;\", \"&lt;record id_2&gt;\"],\n            \"&lt;input descriptor id_2&gt;\": [\"&lt;record id&gt;\"],\n        }\n    },\n    \"reveal_doc\": {\n        // vc_di dict\n    }\n\n}\n</code></pre>"},{"location":"design/AnoncredsW3CCompatibility/#how-a-w3c-credential-is-stored-in-the-wallet","title":"How a W3C credential is stored in the wallet","text":"<p>Storing a credential in the wallet is somewhat dependent on the kinds of metadata that are relevant. The metadata mapping between the W3C credential and an AnonCreds credential is not fully clear yet.</p> <p>One of the questions we need to answer is whether the preferred approach is to modify the existing store credential function so that any credential type is a valid input, or whether there should be a special function just for storing W3C credentials.</p> <p>We will duplicate this store_credential function and modify it:</p> <pre><code>async def store_w3c_credential(...) {\n    ...\n    ...\n    try:\n        cred = W3CCredential.load(credential_data)\n    ...\n    ...\n}\n</code></pre> <p>Question: Would it also be possible to generate the credentials on the fly to eliminate the need for storage?</p> <p>Answer: I don't think it is possible to eliminate the need for storage, and notably the secure storage (encrypted at rest) supported in Askar.</p>"},{"location":"design/AnoncredsW3CCompatibility/#how-can-we-handle-multiple-signatures-on-a-w3c-vc-format-credential","title":"How can we handle multiple signatures on a W3C VC Format credential?","text":"<p>Only one of the signature types (CL) is allowed in the AnonCreds format, so if a W3C VC is created by <code>to_legacy()</code>, all signature types that can't be turned into a CL signature will be dropped. This would make the conversion lossy. Similarly, an AnonCreds credential carries only the CL signature, limiting output from <code>to_w3c()</code> signature types that can be derived from the source CL signature. A possible future enhancement would be to add an extra field to the AnonCreds data structure, in which additional signatures could be stored, even if they are not used. This could eliminate the lossiness, but it adds extra complexity and may not be worth doing.</p> <ul> <li>Unlike a \"typical\" non-AnonCreds W3C VC, an AnonCreds VC is never directly presented to a verifier. Rather, a derivation of the credential is generated, and it is the derivation that is shared with the verifier as a presentation. The derivation:</li> <li>Generates presentation-specific signatures to be verified.</li> <li>Selectively reveals attributes.</li> <li>Generates proofs of the requested predicates.</li> <li>Generates a proof of knowledge of the link secret blinded in the verifiable credential.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#compatibility-with-afj-how-can-we-make-sure-that-we-are-compatible","title":"Compatibility with AFJ: how can we make sure that we are compatible?","text":"<p>We will write a test for the Aries Agent Test Framework that issues a W3C VC instead of an AnonCreds credential, and then run that test where one of the agents is ACA-PY and the other is based on AFJ -- and vice versa. Also write a test where a W3C VC is presented after an AnonCreds issuance, and run it with the two roles played by the two different agents. This is a simple approach, but if the tests pass, this should eliminate almost all risk of incompatibility.</p>"},{"location":"design/AnoncredsW3CCompatibility/#will-we-introduce-new-dependencies-and-what-is-risky-or-easy","title":"Will we introduce new dependencies, and what is risky or easy?","text":"<p>Any significant bugs in the Rust implementation may prevent our wrappers from working, which would also prevent progress (or at least confirmed test results) on the higher-level code.</p> <p>If AFJ lags behind in delivering equivalent functionality, we may not be able to demonstrate compatibility with the test harness.</p>"},{"location":"design/AnoncredsW3CCompatibility/#where-should-the-new-issuance-code-go","title":"Where should the new issuance code go?","text":"<p>So the vc directory contains code to verify vc's, is this a logical place to add the code for issuance?</p>"},{"location":"design/AnoncredsW3CCompatibility/#what-do-we-call-the-new-things-flexcreds-or-just-w3c_xxx","title":"What do we call the new things? Flexcreds? or just W3C_xxx","text":"<p>Are we defining a concept called Flexcreds that is a credential with a proof array that you can generate more specific or limited credentials from? If so should this be included in the naming?</p> <ul> <li>I don't think naming comes into play. We are creating and deriving presentations from VC Data Integrity Proofs using an AnonCreds cryptosuite. As such, these are \"stock\" W3C verifiable credentials.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#how-can-a-wallet-retain-the-capability-to-present-only-an-anoncred-credential","title":"How can a wallet retain the capability to present ONLY an anoncred credential?","text":"<p>If the wallet receives a \"Flexcred\" credential object with an array of proofs, the wallet may wish to present ONLY the more zero-knowledge anoncreds proof</p> <p>How will wallets support that in a way that is developer-friendly to wallet devs?</p> <ul> <li>The trigger for wallets to generate a W3C VP Format presentation is that they have receive a RFC 0510 DIF Presentation Exchange that can be satisfied with an AnonCreds verifiable credential in their storage. Once we decide to use one or more AnonCreds VCs to satisfy a presentation, we'll derive such a presentation and send it using the RFC 0510 DIF Presentation Exchange for the <code>presentation</code> message of the Present Proof v2.0 protocol.</li> </ul>"},{"location":"features/AdminAPI/","title":"ACA-Py Administration API","text":""},{"location":"features/AdminAPI/#using-the-openapi-swagger-interface","title":"Using the OpenAPI (Swagger) Interface","text":"<p>ACA-Py provides an OpenAPI-documented REST interface for administering the agent's internal state and initiating communication with connected agents.</p> <p>To see the specifics of the supported endpoints, as well as the expected request and response formats, it is recommended to run the <code>aca-py</code> agent with the <code>--admin {HOST} {PORT}</code> and <code>--admin-insecure-mode</code> command line parameters. This exposes the OpenAPI UI on the provided port for interaction via a web browser. For production deployments, run the agent with <code>--admin-api-key {KEY}</code> and add the <code>X-API-Key: {KEY}</code> header to all requests instead of using the <code>--admin-insecure-mode</code> parameter.</p> <p></p> <p>To invoke a specific method:</p> <ul> <li>Scroll to and find that endpoint;</li> <li>Click on the endpoint name to expand its section of the UI;</li> <li>Click on the Try it out button;</li> <li>Fill in any data necessary to run the command;</li> <li>Click Execute;</li> <li>Check the response to see if the request worked as expected.</li> </ul> <p>The mechanical steps are easy; however, the fourth step from the list above can be tricky. Supplying the right data and, where JSON is involved, getting the syntax correct\u2014braces and quotes can be a pain. When steps don't work, start your debugging by looking at your JSON. You may also choose to use a REST client like Postman or Insomnia, which will provide syntax highlighting and other features to simplify the process.</p> <p>Because API methods often initiate asynchronous processes, the JSON response provided by an endpoint is not always sufficient to determine the next action. To handle this situation, as well as events triggered by external inputs (such as new connection requests), it is necessary to implement a webhook processor, as detailed in the next section.</p> <p>The combination of an OpenAPI client and webhook processor is referred to as an ACA-Py Controller and is the recommended method to define custom behaviors for your ACA-Py-based agent application.</p>"},{"location":"features/AdminAPI/#administration-api-webhooks","title":"Administration API Webhooks","text":"<p>When ACA-Py is started with the <code>--webhook-url {URL}</code> command line parameter, state-management records are sent to the provided URL via POST requests whenever a record is created or its <code>state</code> property is updated.</p> <p>When a webhook is dispatched, the record <code>topic</code> is appended as a path component to the URL. For example, <code>https://webhook.host.example</code> becomes <code>https://webhook.host.example/topic/connections</code> when a connection record is updated. A POST request is made to the resulting URL with the body of the request comprising a serialized JSON object. The full set of properties of the current set of webhook payloads are listed below. Note that empty (null-value) properties are omitted.</p>"},{"location":"features/AdminAPI/#webhooks-over-websocket","title":"Webhooks over WebSocket","text":"<p>ACA-Py's Admin API also supports delivering webhooks over WebSocket. This can be especially useful when working with scripts that interact with the Admin API but don't have a web server listening to receive webhooks in response to its actions. No additional command line parameters are required to enable WebSocket support.</p> <p>Webhooks received over WebSocket will contain the same data as webhooks posted over http but the structure differs in order to communicate details that would have been received as part of the HTTP request path and headers.</p> <ul> <li><code>topic</code>: The topic of the webhook, such as <code>connections</code> or <code>basicmessages</code></li> <li><code>payload</code>: The payload of the webhook; this is the data usually received in the request body when webhooks are delivered over HTTP</li> <li><code>wallet_id</code>: If using multitenancy, this is the wallet ID of the subwallet that emitted the webhook. This value will be omitted if not using multitenancy.</li> </ul> <p>To open a WebSocket, connect to the <code>/ws</code> endpoint of the Admin API.</p>"},{"location":"features/AdminAPI/#pairwise-connection-record-updated-connections","title":"Pairwise Connection Record Updated (<code>/connections</code>)","text":"<ul> <li><code>connection_id</code>: the unique connection identifier</li> <li><code>state</code>: <code>init</code> / <code>invitation</code> / <code>request</code> / <code>response</code> / <code>active</code> / <code>error</code> / <code>inactive</code></li> <li><code>my_did</code>: the DID this agent is using in the connection</li> <li><code>their_did</code>: the DID the other agent in the connection is using</li> <li><code>their_label</code>: a connection label provided by the other agent</li> <li><code>their_role</code>: a role assigned to the other agent in the connection</li> <li><code>inbound_connection_id</code>: a connection identifier for the related inbound routing connection</li> <li><code>initiator</code>: <code>self</code> / <code>external</code> / <code>multiuse</code></li> <li><code>invitation_key</code>: a verification key used to identify the source connection invitation</li> <li><code>request_id</code>: the <code>@id</code> property from the connection request message</li> <li><code>routing_state</code>: <code>none</code> / <code>request</code> / <code>active</code> / <code>error</code></li> <li><code>accept</code>: <code>manual</code> / <code>auto</code></li> <li><code>error_msg</code>: the most recent error message</li> <li><code>invitation_mode</code>: <code>once</code> / <code>multi</code></li> <li><code>alias</code>: a local alias for the connection record</li> </ul>"},{"location":"features/AdminAPI/#basic-message-received-basicmessages","title":"Basic Message Received (<code>/basicmessages</code>)","text":"<ul> <li><code>connection_id</code>: the identifier of the related pairwise connection</li> <li><code>message_id</code>: the <code>@id</code> of the incoming agent message</li> <li><code>content</code>: the contents of the agent message</li> <li><code>state</code>: <code>received</code></li> </ul>"},{"location":"features/AdminAPI/#forward-message-received-forward","title":"Forward Message Received  (<code>/forward</code>)","text":"<p>Enable using <code>--monitor-forward</code>.</p> <ul> <li><code>connection_id</code>: the identifier of the connection associated with the recipient key</li> <li><code>recipient_key</code>: the recipient key of the forward message (<code>to</code> field of the forward message)</li> <li><code>status</code>: The delivery status of the received forward message. Possible values:</li> <li><code>sent_to_session</code>: Message is sent directly to the connection over an active transport session</li> <li><code>sent_to_external_queue</code>: Message is sent to an external queue. No information is known on the delivery of the message</li> <li><code>queued_for_delivery</code>: Message is queued for delivery using outbound transport (recipient connection has an endpoint)</li> <li><code>waiting_for_pickup</code>: The connection has no reachable endpoint. Need to wait for the recipient to connect with return routing for delivery</li> <li><code>undeliverable</code>: The connection has no reachable endpoint, and the internal queue for messages is not enabled (<code>--enable-undelivered-queue</code>).</li> </ul>"},{"location":"features/AdminAPI/#credential-exchange-record-updated-issue_credential","title":"Credential Exchange Record Updated (<code>/issue_credential</code>)","text":"<ul> <li><code>credential_exchange_id</code>: the unique identifier of the credential exchange</li> <li><code>connection_id</code>: the identifier of the related pairwise connection</li> <li><code>thread_id</code>: the thread ID of the previously received credential proposal or offer</li> <li><code>parent_thread_id</code>: the parent thread ID of the previously received credential proposal or offer</li> <li><code>initiator</code>: issue-credential exchange initiator <code>self</code> / <code>external</code></li> <li><code>state</code>: <code>proposal_sent</code> / <code>proposal_received</code> / <code>offer_sent</code> / <code>offer_received</code> / <code>request_sent</code> / <code>request_received</code> / <code>issued</code> / <code>credential_received</code> / <code>credential_acked</code></li> <li><code>credential_definition_id</code>: the ledger identifier of the related credential definition</li> <li><code>schema_id</code>: the ledger identifier of the related credential schema</li> <li><code>credential_proposal_dict</code>: the credential proposal message</li> <li><code>credential_offer</code>: (Indy) credential offer</li> <li><code>credential_request</code>: (Indy) credential request</li> <li><code>credential_request_metadata</code>: (Indy) credential request metadata</li> <li><code>credential_id</code>: the wallet identifier of the stored credential</li> <li><code>raw_credential</code>: the credential record as received</li> <li><code>credential</code>: the credential record as stored in the wallet</li> <li><code>auto_offer</code>: (boolean) whether to automatically offer the credential</li> <li><code>auto_issue</code>: (boolean) whether to automatically issue the credential</li> <li><code>error_msg</code>: the previous error message</li> </ul>"},{"location":"features/AdminAPI/#presentation-exchange-record-updated-present_proof","title":"Presentation Exchange Record Updated (<code>/present_proof</code>)","text":"<ul> <li><code>presentation_exchange_id</code>: the unique identifier of the presentation exchange</li> <li><code>connection_id</code>: the identifier of the related pairwise connection</li> <li><code>thread_id</code>: the thread ID of the previously received presentation proposal or offer</li> <li><code>initiator</code>: present-proof exchange initiator: <code>self</code> / <code>external</code></li> <li><code>state</code>: <code>proposal_sent</code> / <code>proposal_received</code> / <code>request_sent</code> / <code>request_received</code> / <code>presentation_sent</code> / <code>presentation_received</code> / <code>verified</code></li> <li><code>presentation_proposal_dict</code>: the presentation proposal message</li> <li><code>presentation_request</code>: (Indy) presentation request (also known as proof request)</li> <li><code>presentation</code>: (Indy) presentation (also known as proof)</li> <li><code>verified</code>: (string) whether the presentation is verified: <code>true</code> or <code>false</code></li> <li><code>auto_present</code>: (boolean) prover choice to auto-present proof as verifier requests</li> <li><code>error_msg</code>: the previous error message</li> </ul>"},{"location":"features/AdminAPI/#api-standard-behavior","title":"API Standard Behavior","text":"<p>The best way to develop a new admin API or protocol is to follow one of the existing protocols, such as the Credential Exchange or Presentation Exchange.</p> <p>The <code>routes.py</code> file contains the API definitions - API endpoints and payload schemas (note that these are not the Aries message schemas).</p> <p>The payload schemas are defined using marshmallow and will be validated automatically when the API is executed (using middleware). (This raises a status <code>422</code> HTTP response with an error message if the schema validation fails.)</p> <p>API endpoints are defined using aiohttp_apispec tags (e.g. <code>@doc</code>, <code>@request_schema</code>, <code>@response_schema</code> etc.) which define the input and output parameters of the endpoint. API URL paths are defined in the <code>register()</code> method and added to the Swagger page in the <code>post_process_routes()</code> method.</p> <p>The APIs should return the following HTTP status:</p> <ul> <li>HTTP 200 for successful API completion, with an appropriate response</li> <li>HTTP 400 (or appropriate 4xx code) (with an error message) for errors on input parameters (i.e., the user can retry with different parameters and potentially get a successful API call)</li> <li>HTTP 404 if a record is expected and not found (generally for GET requests that fetch a single record)</li> <li>HTTP 500 (or appropriate 5xx code) if there is some other processing error (i.e., it won't make any difference what parameters the user tries) with an error message</li> </ul> <p>...and should not return:</p> <ul> <li>HTTP 500 with a stack trace due to an untrapped error (we should handle error conditions with a 400 or 404 response and catch errors, providing a meaningful error message)</li> </ul>"},{"location":"features/AnoncredsProofValidation/","title":"Anoncreds Proof Validation in ACA-Py","text":"<p>ACA-Py performs pre-validation when verifying Anoncreds presentations (proofs). Some scenarios are rejected (such as those indicative of tampering), while some attributes are removed before running the anoncreds validation (e.g., removing superfluous non-revocation timestamps). Any ACA-Py validations or presentation modifications are indicated by the \"verify_msgs\" attribute in the final presentation exchange object.</p> <p>The list of possible verification messages can be found here, and consists of:</p> <pre><code>class PresVerifyMsg(str, Enum):\n    \"\"\"Credential verification codes.\"\"\"\n\n    RMV_REFERENT_NON_REVOC_INTERVAL = \"RMV_RFNT_NRI\"\n    RMV_GLOBAL_NON_REVOC_INTERVAL = \"RMV_GLB_NRI\"\n    TSTMP_OUT_NON_REVOC_INTRVAL = \"TS_OUT_NRI\"\n    CT_UNREVEALED_ATTRIBUTES = \"UNRVL_ATTR\"\n    PRES_VALUE_ERROR = \"VALUE_ERROR\"\n    PRES_VERIFY_ERROR = \"VERIFY_ERROR\"\n</code></pre> <p>If there is additional information, it will be included like this: <code>TS_OUT_NRI::19_uuid</code> (which means the attribute identified by <code>19_uuid</code> contained a timestamp outside of the non-revocation interval (this is just a warning)).</p> <p>A presentation verification may include multiple messages, for example:</p> <pre><code>    ...\n    \"verified\": \"true\",\n    \"verified_msgs\": [\n        \"TS_OUT_NRI::18_uuid\",\n        \"TS_OUT_NRI::18_id_GE_uuid\",\n        \"TS_OUT_NRI::18_busid_GE_uuid\"\n    ],\n    ...\n</code></pre> <p>... or it may include a single message, for example:</p> <pre><code>    ...\n    \"verified\": \"false\",\n    \"verified_msgs\": [\n        \"VALUE_ERROR::Encoded representation mismatch for 'Preferred Name'\"\n    ],\n    ...\n</code></pre> <p>... or the <code>verified_msgs</code> may be null or an empty array.</p>"},{"location":"features/AnoncredsProofValidation/#presentation-modifications-and-warnings","title":"Presentation Modifications and Warnings","text":"<p>The following modifications/warnings may be made by ACA-Py, which shouldn't affect the verification of the received proof:</p> <ul> <li>\"RMV_RFNT_NRI\": Referent contains a non-revocation interval for a non-revocable credential (timestamp is removed)</li> <li>\"RMV_GLB_NRI\": Presentation contains a global interval for a non-revocable credential (timestamp is removed)</li> <li>\"TS_OUT_NRI\": Presentation contains a non-revocation timestamp outside of the requested non-revocation interval (warning)</li> <li>\"UNRVL_ATTR\": Presentation contains attributes with unrevealed values (warning)</li> </ul>"},{"location":"features/AnoncredsProofValidation/#presentation-pre-validation-errors","title":"Presentation Pre-validation Errors","text":"<p>The following pre-verification checks are performed, which will cause the proof to fail (before calling anoncreds) and result in the following message:</p> <pre><code>VALUE_ERROR::&lt;description of the failed validation&gt;\n</code></pre> <p>These validations are all performed within the Indy verifier class - to see the detailed validation, look for any occurrences of <code>raise ValueError(...)</code> in the code.</p> <p>A summary of the possible errors includes:</p> <ul> <li>Information missing in presentation exchange record</li> <li>Timestamp provided for irrevocable credential</li> <li>Referenced revocation registry not found on ledger</li> <li>Timestamp outside of reasonable range (future date or pre-dates revocation registry)</li> <li>Mismatch between provided and requested timestamps for non-revocation</li> <li>Mismatch between requested and provided attributes or predicates</li> <li>Self-attested attribute provided for a requested attribute with restrictions</li> <li>Encoded value doesn't match raw value</li> </ul>"},{"location":"features/AnoncredsProofValidation/#anoncreds-verification-exceptions","title":"Anoncreds Verification Exceptions","text":"<p>Typically, when you call the anoncreds <code>verifier_verify_proof()</code> method, it will return a <code>True</code> or <code>False</code> based on whether the presentation cryptographically verifies. However, in the case where anoncreds throws an exception, the exception text will be included in a verification message as follows:</p> <pre><code>VERIFY_ERROR::&lt;the exception text&gt;\n</code></pre>"},{"location":"features/DIDMethods/","title":"DID Methods in ACA-Py","text":"<p>Decentralized Identifiers, or DIDs, are URIs that point to documents that describe cryptographic primitives and protocols used in decentralized identity management. DIDs include methods that describe where and how documents can be retrieved. DID methods support specific types of keys and may or may not require the holder to specify the DID itself.</p> <p>ACA-Py provides a <code>DIDMethods</code> registry holding all the DID methods supported for storage in a wallet</p> <p> Askar and InMemory are the only wallets supporting this registry.</p>"},{"location":"features/DIDMethods/#registering-a-did-method","title":"Registering a DID method","text":"<p>By default, ACA-Py supports <code>did:key</code> and <code>did:sov</code>. Plugins can register DID additional methods to make them available to holders. Here's a snippet adding support for <code>did:web</code> to the registry from a plugin <code>setup</code> method.</p> <pre><code>WEB = DIDMethod(\n    name=\"web\",\n    key_types=[ED25519, BLS12381G2],\n    rotation=True,\n    holder_defined_did=HolderDefinedDid.REQUIRED  # did:web is not derived from key material but from a user-provided repository name\n)\n\nasync def setup(context: InjectionContext):\n    methods = context.inject(DIDMethods)\n    methods.register(WEB)\n</code></pre>"},{"location":"features/DIDMethods/#creating-a-did","title":"Creating a DID","text":"<p><code>POST /wallet/did/create</code> can be provided with parameters for any registered DID method. Here's a follow-up to the <code>did:web</code> method example:</p> <pre><code>{\n    \"method\": \"web\",\n    \"options\": {\n        \"did\": \"did:web:doma.in\",\n        \"key_type\": \"ed25519\"\n    }\n}\n</code></pre>"},{"location":"features/DIDMethods/#resolving-dids","title":"Resolving DIDs","text":"<p>For specifics on how DIDs are resolved in ACA-Py, see: DID Resolution.</p>"},{"location":"features/DIDResolution/","title":"DID Resolution in ACA-Py","text":"<p>Decentralized Identifiers, or DIDs, are URIs that point to documents that describe cryptographic primitives and protocols used in decentralized identity management. DIDs include methods that describe where and how documents can be retrieved. DID resolution is the process of \"resolving\" a DID Document from a DID as dictated by the DID method.</p> <p>A DID Resolver is a piece of software that implements the methods for resolving a document from a DID.</p> <p>For example, given the DID <code>did:example:1234abcd</code>, a DID Resolver that supports <code>did:example</code> might return:</p> <pre><code>{\n \"@context\": \"https://www.w3.org/ns/did/v1\",\n \"id\": \"did:example:1234abcd\",\n \"verificationMethod\": [{\n  \"id\": \"did:example:1234abcd#keys-1\",\n  \"type\": \"Ed25519VerificationKey2018\",\n  \"controller\": \"did:example:1234abcd\",\n  \"publicKeyBase58\": \"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"\n }],\n \"service\": [{\n  \"id\": \"did:example:1234abcd#did-communication\",\n  \"type\": \"did-communication\",\n  \"serviceEndpoint\": \"https://agent.example.com/8377464\"\n }]\n}\n</code></pre> <p>For more details on DIDs and DID Resolution, see the W3C DID Specification.</p> <p>In practice, DIDs and DID Documents are used for a variety of purposes but especially to help establish connections between Agents and verify credentials.</p>"},{"location":"features/DIDResolution/#didresolver","title":"<code>DIDResolver</code>","text":"<p>In ACA-Py, the <code>DIDResolver</code> provides the interface to resolve DIDs using registered method resolvers. Method resolver registration happens on startup in a <code>did_resolvers</code> list. This registry enables additional resolvers to be loaded via plugin.</p>"},{"location":"features/DIDResolution/#example-usage","title":"Example usage","text":"<pre><code>class ExampleMessageHandler:\n    async def handle(context: RequestContext, responder: BaseResponder):\n    \"\"\"Handle example message.\"\"\"\n    resolver = await context.inject(DIDResolver)\n\n    doc: dict = await resolver.resolve(\"did:example:123\")\n    assert doc[\"id\"] == \"did:example:123\"\n\n    verification_method = await resolver.dereference(\"did:example:123#keys-1\")\n\n    # ...\n</code></pre>"},{"location":"features/DIDResolution/#method-resolver-selection","title":"Method Resolver Selection","text":"<p>On <code>DIDResolver.resolve</code> or <code>DIDResolver.dereference</code>, the resolver interface will select the most appropriate method resolver to handle the given DID. In this selection process, method resolvers are distinguished from each other by:</p> <ul> <li>Type. The resolver's type falls into one of two categories: native or non-native. A \"native\" resolver will perform all resolution steps directly. A \"non-native\" resolver delegates all or part of resolution to another service or entity.</li> <li>Self-reported supported DIDs. Each method resolver implements a <code>supports</code> method or a <code>supported_did_regex</code> method. These methods are used to determine whether the given DID can be handled by the method resolver.</li> </ul> <p>The selection algorithm roughly follows the following steps:</p> <ol> <li>Filter out all resolvers where <code>resolver.supports(did)</code> returns <code>false</code>.</li> <li>Partition remaining resolvers by type with all native resolvers followed by non-native resolvers (registration order preserved within partitions).</li> <li>For each resolver in the resulting list, attempt to resolve the DID and return the first successful result.</li> </ol>"},{"location":"features/DIDResolution/#resolver-plugins","title":"Resolver Plugins","text":"<p>Extending ACA-Py with additional Method Resolvers should be relatively simple. Supposing that you want to resolve DIDs for the <code>did:cool</code> method, this should be as simple as installing a method resolver into your python environment and loading the resolver on startup. If no method resolver exists yet for <code>did:cool</code>, writing your own should require minimal overhead.</p>"},{"location":"features/DIDResolution/#writing-a-resolver-plugin","title":"Writing a resolver plugin","text":"<p>Method resolver plugins are composed of two primary pieces: plugin injection and resolution logic. The resolution logic dictates how a DID becomes a DID Document, following the given DID Method Specification. This logic is implemented using the <code>BaseDIDResolver</code> class as the base. <code>BaseDIDResolver</code> is an abstract base class that defines the interface that the core <code>DIDResolver</code> expects for Method resolvers.</p> <p>The following is an example method resolver implementation. In this example, we have 2 files, one for each piece (injection and resolution). The <code>__init__.py</code> will be in charge of injecting the plugin, and <code>example_resolver.py</code> will have the logic implementation to resolve for a fabricated <code>did:example</code> method.</p>"},{"location":"features/DIDResolution/#__init-__py","title":"<code>__init __.py</code>","text":"<p>```python= from aries_cloudagent.config.injection_context import InjectionContext from ..resolver.did_resolver import DIDResolver</p> <p>from .example_resolver import ExampleResolver</p> <p>async def setup(context: InjectionContext):     \"\"\"Setup the plugin.\"\"\"     registry = context.inject(DIDResolver)     resolver = ExampleResolver()     await resolver.setup(context)     registry.append(resolver) <pre><code>#### `example_resolver.py`\n\n```python=\nimport re\nfrom typing import Pattern\nfrom aries_cloudagent.resolver.base import BaseDIDResolver, ResolverType\n\nclass ExampleResolver(BaseDIDResolver):\n    \"\"\"ExampleResolver class.\"\"\"\n\n    def __init__(self):\n        super().__init__(ResolverType.NATIVE)\n        # Alternatively, ResolverType.NON_NATIVE\n        self._supported_did_regex = re.compile(\"^did:example:.*$\")\n\n    @property\n    def supported_did_regex(self) -&gt; Pattern:\n        \"\"\"Return compiled regex matching supported DIDs.\"\"\"\n        return self._supported_did_regex\n\n    async def setup(self, context):\n        \"\"\"Setup the example resolver (none required).\"\"\"\n\n    async def _resolve(self, profile: Profile, did: str) -&gt; dict:\n        \"\"\"Resolve example DIDs.\"\"\"\n        if did != \"did:example:1234abcd\":\n            raise DIDNotFound(\n                \"We only actually resolve did:example:1234abcd. Sorry!\"\n            )\n\n        return {\n            \"@context\": \"https://www.w3.org/ns/did/v1\",\n            \"id\": \"did:example:1234abcd\",\n            \"verificationMethod\": [{\n                \"id\": \"did:example:1234abcd#keys-1\",\n                \"type\": \"Ed25519VerificationKey2018\",\n                \"controller\": \"did:example:1234abcd\",\n                \"publicKeyBase58\": \"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"\n            }],\n            \"service\": [{\n                \"id\": \"did:example:1234abcd#did-communication\",\n                \"type\": \"did-communication\",\n                \"serviceEndpoint\": \"https://agent.example.com/\"\n            }]\n        }\n</code></pre></p>"},{"location":"features/DIDResolution/#errors","title":"Errors","text":"<p>There are 3 different errors associated with resolution in ACA-Py that could be used for development purposes.</p> <ul> <li>ResolverError</li> <li>Base class for resolver exceptions.</li> <li>DIDNotFound</li> <li>Raised when DID is not found using DID method specific algorithm.</li> <li>DIDMethodNotSupported</li> <li>Raised when no resolver is registered for a given did method.</li> </ul>"},{"location":"features/DIDResolution/#using-resolver-plugins","title":"Using Resolver Plugins","text":"<p>In this section, the Github Resolver Plugin found here will be used as an example plugin to work with. This resolver resolves <code>did:github</code> DIDs.</p> <p>The resolution algorithm is simple: for the github DID <code>did:github:dbluhm</code>, the method specific identifier <code>dbluhm</code> (a GitHub username) is used to lookup an <code>index.jsonld</code> file in the <code>ghdid</code> repository in that GitHub users profile. See GitHub DID Method Specification for more details.</p> <p>To use this plugin, first install it into your project's python environment:</p> <pre><code>pip install git+https://github.com/dbluhm/acapy-resolver-github\n</code></pre> <p>Then, invoke ACA-Py as you normally do with the addition of:</p> <pre><code>$ aca-py start \\\n    --plugin acapy_resolver_github \\\n    # ... the remainder of your startup arguments\n</code></pre> <p>Or add the following to your configuration file:</p> <pre><code>plugin:\n  - acapy_resolver_github\n</code></pre> <p>The following is a fully functional Dockerfile encapsulating this setup:</p> <p>```dockerfile= FROM ghcr.io/hyperledger/aries-cloudagent-python:py3.9-0.12.0rc1 RUN pip3 install git+https://github.com/dbluhm/acapy-resolver-github</p> <p>CMD [\"aca-py\", \"start\", \"-it\", \"http\", \"0.0.0.0\", \"3000\", \"-ot\", \"http\", \"-e\", \"http://localhost:3000\", \"--admin\", \"0.0.0.0\", \"3001\", \"--admin-insecure-mode\", \"--no-ledger\", \"--plugin\", \"acapy_resolver_github\"] <pre><code>To use the above dockerfile:\n\n```shell\ndocker build -t resolver-example .\ndocker run --rm -it -p 3000:3000 -p 3001:3001 resolver-example\n</code></pre></p>"},{"location":"features/DIDResolution/#directory-of-resolver-plugins","title":"Directory of Resolver Plugins","text":"<ul> <li>Github Resolver</li> <li>Universal Resolver</li> <li>DIDComm Resolver</li> </ul>"},{"location":"features/DIDResolution/#references","title":"References","text":"<p>https://www.w3.org/TR/did-core/ https://w3c-ccg.github.io/did-resolution/</p>"},{"location":"features/DevReadMe/","title":"Developer's Read Me for Hyperledger Aries Cloud Agent - Python","text":"<p>See the README for details about this repository and information about how the Aries Cloud Agent - Python fits into the Aries project and relates to Indy.</p>"},{"location":"features/DevReadMe/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Introduction</li> <li>Developer Demos</li> <li>Running</li> <li>Configuring ACA-PY: Command Line Parameters</li> <li>Docker</li> <li>Locally Installed</li> <li>About ACA-Py Command Line Parameters</li> <li>Provisioning Secure Storage</li> <li>Mediation</li> <li>Multi-tenancy</li> <li>JSON-LD Credentials</li> <li>Developing</li> <li>Prerequisites</li> <li>Running In A Dev Container</li> <li>Running Locally</li> <li>Logging</li> <li>Running Tests</li> <li>Running Aries Agent Test Harness Tests</li> <li>Development Workflow</li> <li>Publishing Releases</li> <li>Dynamic Injection of Services</li> </ul>"},{"location":"features/DevReadMe/#introduction","title":"Introduction","text":"<p>Aries Cloud Agent Python (ACA-Py) is a configurable, extensible, non-mobile Aries agent that implements an easy way for developers to build decentralized identity services that use verifiable credentials.</p> <p>The information on this page assumes you are developer with a background in decentralized identity, Aries, DID Methods, and verifiable credentials, especially AnonCreds. If you aren't familiar with those concepts and projects, please use our Getting Started Guide to learn more.</p>"},{"location":"features/DevReadMe/#developer-demos","title":"Developer Demos","text":"<p>To put ACA-Py through its paces at the command line, checkout our demos page.</p>"},{"location":"features/DevReadMe/#running","title":"Running","text":""},{"location":"features/DevReadMe/#configuring-aca-py-command-line-parameters","title":"Configuring ACA-PY: Command Line Parameters","text":"<p>ACA-Py agent instances are configured through the use of command line parameters, environment variables and/or YAML files. All of the configurations settings can be managed using any combination of the three methods (command line parameters override environment variables override YAML). Use the <code>--help</code> option to discover the available command line parameters. There are a lot of them--for good and bad.</p>"},{"location":"features/DevReadMe/#docker","title":"Docker","text":"<p>To run a docker container based on the code in the current repo, use the following commands from the root folder of the repository to check the version, list the available modes of operation, and see all of the command line parameters:</p> <pre><code>scripts/run_docker --version\nscripts/run_docker --help\nscripts/run_docker provision --help\nscripts/run_docker start --help\n</code></pre>"},{"location":"features/DevReadMe/#locally-installed","title":"Locally Installed","text":"<p>If you installed the PyPi package, the executable <code>aca-py</code> should be available on your PATH.</p> <p>Use the following commands from the root folder of the repository to check the version, list the available modes of operation, and see all of the command line parameters:</p> <pre><code>aca-py --version\naca-py --help\naca-py provision --help\naca-py start --help\n</code></pre> <p>If you get an error about a missing module <code>indy</code> (e.g. <code>ModuleNotFoundError: No module named 'indy'</code>) when running <code>aca-py</code>, you will need to install the Indy libraries from the command line:</p> <pre><code>pip install python3_indy\n</code></pre> <p>Once that completes successfully, you should be able to run <code>aca-py --version</code> and the other examples above.</p>"},{"location":"features/DevReadMe/#about-aca-py-command-line-parameters","title":"About ACA-Py Command Line Parameters","text":"<p>ACA-Py invocations are separated into two types - initially provisioning an agent (<code>provision</code>) and starting a new agent process (<code>start</code>). This separation enables not having to pass in some encryption-related parameters required for provisioning when starting an agent instance. This improves security in production deployments.</p> <p>When starting an agent instance, at least one inbound and one outbound transport MUST be specified.</p> <p>For example:</p> <pre><code>aca-py start    --inbound-transport http 0.0.0.0 8000 \\\n                --outbound-transport http\n</code></pre> <p>or</p> <pre><code>aca-py start    --inbound-transport http 0.0.0.0 8000 \\\n                --inbound-transport ws 0.0.0.0 8001 \\\n                --outbound-transport ws \\\n                --outbound-transport http\n</code></pre> <p>ACA-Py ships with both inbound and outbound transport drivers for <code>http</code> and <code>ws</code> (websockets). Additional transport drivers can be added as pluggable implementations. See the existing implementations in the transports module for getting started on adding a new transport.</p> <p>Most configuration parameters are provided to the agent at startup. Refer to the <code>Running</code> sections above for details on listing the available command line parameters.</p>"},{"location":"features/DevReadMe/#provisioning-secure-storage","title":"Provisioning Secure Storage","text":"<p>It is possible to provision a secure storage (sometimes called a wallet--but not the same as a mobile wallet app) before running an agent to avoid passing in the secure storage seed on every invocation of an agent (e.g. on every <code>aca-py start ...</code>).</p> <pre><code>aca-py provision --wallet-type askar --seed $SEED\n</code></pre> <p>For additional <code>provision</code> options, execute <code>aca-py provision --help</code>.</p> <p>Additional information about secure storage options and configuration settings can be found here.</p>"},{"location":"features/DevReadMe/#mediation","title":"Mediation","text":"<p>ACA-Py can also run in mediator mode - ACA-Py can be run as a mediator (it can mediate connections for other agents), or it can connect to an external mediator to mediate its own connections.  See the docs on mediation for more info.</p>"},{"location":"features/DevReadMe/#multi-tenancy","title":"Multi-tenancy","text":"<p>ACA-Py can also be started in multi-tenant mode. This allows the agent to serve multiple tenants, that each have their own wallet. See the docs on multi-tenancy for more info.</p>"},{"location":"features/DevReadMe/#json-ld-credentials","title":"JSON-LD Credentials","text":"<p>ACA-Py can issue W3C Verifiable Credentials using Linked Data Proofs. See the docs on JSON-LD Credentials for more info.</p>"},{"location":"features/DevReadMe/#developing","title":"Developing","text":""},{"location":"features/DevReadMe/#prerequisites","title":"Prerequisites","text":"<p>Docker must be installed to run software locally and to run the test suite.</p>"},{"location":"features/DevReadMe/#running-in-a-dev-container","title":"Running In A Dev Container","text":"<p>The dev container environment is a great way to deploy agents quickly with code changes and an interactive debug session. Detailed information can be found in the Docs On Devcontainers. It is specific for vscode, so if you prefer another code editor or IDE you will need to figure it out on your own, but it is highly recommended to give this a try.</p> <p>One thing to be aware of is, unlike the demo, none of the steps are automated. You will need to create public dids, connections and all the other steps yourself. Using the demo and studying the flow and then copying them with your dev container debug session is a great way to learn how everything works.</p>"},{"location":"features/DevReadMe/#running-locally","title":"Running Locally","text":"<p>Another way to develop locally is by using the provided Docker scripts to run the ACA-Py software.</p> <pre><code>./scripts/run_docker start &lt;args&gt;\n</code></pre> <p>For example:</p> <pre><code>./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG\n</code></pre> <p>To enable the ptvsd Python debugger for Visual Studio/VSCode use the <code>--debug</code> command line parameter.</p> <p>Any ports you will be using from the docker container should be published using the <code>PORTS</code> environment variable. For example:</p> <pre><code>PORTS=\"5000:5000 8000:8000 10000:10000\" ./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG\n</code></pre> <p>Refer to the previous section for instructions on how to run ACA-Py.</p>"},{"location":"features/DevReadMe/#logging","title":"Logging","text":"<p>You can find more details about logging and log levels here.</p>"},{"location":"features/DevReadMe/#running-tests","title":"Running Tests","text":"<p>To run the ACA-Py test suite, use the following script:</p> <pre><code>./scripts/run_tests\n</code></pre> <p>To run the ACA-Py test suite with ptvsd debugger enabled:</p> <pre><code>./scripts/run_tests --debug\n</code></pre> <p>To run specific tests pass parameters as defined by pytest:</p> <pre><code>./scripts/run_tests aries_cloudagent/protocols/connections\n</code></pre> <p>To run the tests including Indy SDK and related dependencies, run the script:</p> <pre><code>./scripts/run_tests_indy\n</code></pre>"},{"location":"features/DevReadMe/#running-aries-agent-test-harness-tests","title":"Running Aries Agent Test Harness Tests","text":"<p>You can run a full suite of integration tests using the Aries Agent Test Harness (AATH).</p> <p>Check out and run AATH tests as follows (this tests the aca-py <code>main</code> branch):</p> <pre><code>git clone https://github.com/hyperledger/aries-agent-test-harness.git\ncd aries-agent-test-harness\n./manage build -a acapy-main\n./manage run -d acapy-main -t @AcceptanceTest -t ~@wip\n</code></pre> <p>The <code>manage</code> script is described in detail here, including how to modify the AATH code to run the tests against your aca-py repo/branch.</p>"},{"location":"features/DevReadMe/#development-workflow","title":"Development Workflow","text":"<p>We use Ruff to enforce a coding style guide.</p> <p>We use Black to automatically format code.</p> <p>Please write tests for the work that you submit.</p> <p>Tests should reside in a directory named <code>tests</code> alongside the code under test. Generally, there is one test file for each file module under test. Test files must have a name starting with <code>test_</code> to be automatically picked up the test runner.</p> <p>There are some good examples of various test scenarios for you to work from including mocking external imports and working with async code so take a look around!</p> <p>The test suite also displays the current code coverage after each run so you can see how much of your work is covered by tests. Use your best judgement for how much coverage is sufficient.</p> <p>Please also refer to the contributing guidelines and code of conduct.</p>"},{"location":"features/DevReadMe/#publishing-releases","title":"Publishing Releases","text":"<p>The publishing document provides information on tagging a release and publishing the release artifacts to PyPi.</p>"},{"location":"features/DevReadMe/#dynamic-injection-of-services","title":"Dynamic Injection of Services","text":"<p>The Agent employs a dynamic injection system whereby providers of base classes are registered with the <code>RequestContext</code> instance, currently within <code>conductor.py</code>. Message handlers and services request an instance of the selected implementation using <code>context.inject(BaseClass)</code>; for instance the wallet instance may be injected using <code>wallet = context.inject(BaseWallet)</code>. The <code>inject</code> method normally throws an exception if no implementation of the base class is provided, but can be called with <code>required=False</code> for optional dependencies (in which case a value of <code>None</code> may be returned).</p> <p>Providers are registered with either <code>context.injector.bind_instance(BaseClass, instance)</code> for previously-constructed (singleton) object instances, or <code>context.injector.bind_provider(BaseClass, provider)</code> for dynamic providers. In some cases it may be desirable to write a custom provider which switches implementations based on configuration settings, such as the wallet provider.</p> <p>The <code>BaseProvider</code> classes in the <code>config.provider</code> module include <code>ClassProvider</code>, which can perform dynamic module inclusion when given the combined module and class name as a string (for instance <code>aries_cloudagent.wallet.indy.IndyWallet</code>). <code>ClassProvider</code> accepts additional positional and keyword arguments to be passed into the class constructor. Any of these arguments may be an instance of <code>ClassProvider.Inject(BaseClass)</code>, allowing dynamic injection of dependencies when the class instance is instantiated.</p>"},{"location":"features/Endorser/","title":"Transaction Endorser Support","text":"<p>ACA-Py supports an Endorser Protocol, that allows an un-privileged agent (an \"Author\") to request another agent (the \"Endorser\") to sign their transactions so they can write these transactions to the ledger.  This is required on Indy ledgers, where new agents will typically be granted only \"Author\" privileges.</p> <p>Transaction Endorsement is built into the protocols for Schema, Credential Definition and Revocation, and endorsements can be explicitly requested, or ACA-Py can be configured to automate the endorsement workflow.</p>"},{"location":"features/Endorser/#setting-up-connections-between-authors-and-endorsers","title":"Setting up Connections between Authors and Endorsers","text":"<p>Since endorsement involves message exchange between two agents, these agents must establish and configure a connection before any endorsements can be provided or requested.</p> <p>Once the connection is established and <code>active</code>, the \"role\" (either Author or Endorser) is attached to the connection using the <code>/transactions/{conn_id}/set-endorser-role</code> endpoint.  For Authors, they must additionally configure the DID of the Endorser as this is required when the Author signs the transaction (prior to sending to the Endorser for endorsement) - this is done using the <code>/transactions/{conn_id}/set-endorser-info</code> endpoint.</p>"},{"location":"features/Endorser/#requesting-transaction-endorsement","title":"Requesting Transaction Endorsement","text":"<p>Transaction Endorsement is built into the protocols for Schema, Credential Definition and Revocation.  When executing one of the endpoints that will trigger a ledger write, an endorsement protocol can be explicitly requested by specifying the <code>connection_id</code> (of the Endorser connection) and <code>create_transaction_for_endorser</code>.</p> <p>(Note that endorsement requests can be automated, see the section on \"Configuring ACA-Py\" below.)</p> <p>If transaction endorsement is requested, then ACA-Py will create a transaction record (this will be returned by the endpoint, rather than the Schema, Cred Def, etc) and the following endpoints must be invoked:</p> Protocol Step Author Endorser Request Endorsement <code>/transactions/create-request</code> Endorse Transaction <code>/transactions/{tran_id}/endorse</code> Write Transaction <code>/transactions/{tran_id}/write</code> <p>Additional endpoints allow the Endorser to reject the endorsement request, or for the Author to re-submit or cancel a request.</p> <p>Web hooks will be triggered to notify each ACA-Py agent of any transaction request, endorsements, etc to allow the controller to react to the event, or the process can be automated via command-line parameters (see below).</p>"},{"location":"features/Endorser/#configuring-aca-py-for-auto-or-manual-endorsement","title":"Configuring ACA-Py for Auto or Manual Endorsement","text":"<p>The following start-up parameters are supported by ACA-Py:</p> <pre><code>Endorsement:\n  --endorser-protocol-role &lt;endorser-role&gt;\n                        Specify the role ('author' or 'endorser') which this agent will participate. Authors will request transaction endorsement from an Endorser. Endorsers will endorse transactions from\n                        Authors, and may write their own transactions to the ledger. If no role (or 'none') is specified then the endorsement protocol will not be used and this agent will write transactions to\n                        the ledger directly. [env var: ACAPY_ENDORSER_ROLE]\n  --endorser-public-did &lt;endorser-public-did&gt;\n                        For transaction Authors, specify the public DID of the Endorser agent who will be endorsing transactions. Note this requires that the connection be made using the Endorser's public\n                        DID. [env var: ACAPY_ENDORSER_PUBLIC_DID]\n  --endorser-alias &lt;endorser-alias&gt;\n                        For transaction Authors, specify the alias of the Endorser connection that will be used to endorse transactions. [env var: ACAPY_ENDORSER_ALIAS]\n  --auto-request-endorsement\n                        For Authors, specify whether to automatically request endorsement for all transactions. (If not specified, the controller must invoke the request endorse operation for each\n                        transaction.) [env var: ACAPY_AUTO_REQUEST_ENDORSEMENT]\n  --auto-endorse-transactions\n                        For Endorsers, specify whether to automatically endorse any received endorsement requests. (If not specified, the controller must invoke the endorsement operation for each transaction.)\n                        [env var: ACAPY_AUTO_ENDORSE_TRANSACTIONS]\n  --auto-write-transactions\n                        For Authors, specify whether to automatically write any endorsed transactions. (If not specified, the controller must invoke the write transaction operation for each transaction.) [env\n                        var: ACAPY_AUTO_WRITE_TRANSACTIONS]\n  --auto-create-revocation-transactions\n                        For Authors, specify whether to automatically create transactions for a cred def's revocation registry. (If not specified, the controller must invoke the endpoints required to create\n                        the revocation registry and assign to the cred def.) [env var: ACAPY_CREATE_REVOCATION_TRANSACTIONS]\n  --auto-promote-author-did\n                        For Authors, specify whether to automatically promote a DID to the wallet public DID after writing to the ledger. [env var: ACAPY_AUTO_PROMOTE_AUTHOR_DID]\n</code></pre>"},{"location":"features/Endorser/#how-aca-py-handles-endorsements","title":"How Aca-py Handles Endorsements","text":"<p>Internally, the Endorsement functionality is implemented as a protocol, and is implemented consistently with other protocols:</p> <ul> <li>a routes.py file exposes the admin endpoints</li> <li>handler files implement responses to any received Endorse protocol messages</li> <li>a manager.py file implements common functionality that is called from both the routes.py and handler classes (as well as from other classes that need to interact with Endorser functionality)</li> </ul> <p>The Endorser makes use of the Event Bus (links to the PR which links to a hackmd doc) to notify other protocols of any Endorser events of interest.  For example, after a Credential Definition endorsement is received, the TransactionManager writes the endorsed transaction to the ledger and uses the Event Bus to notify the Credential Definition manager that it can do any required post-processing (such as writing the cred def record to the wallet, initiating the revocation registry, etc.).</p> <p>The overall architecture can be illustrated as:</p> <p></p>"},{"location":"features/Endorser/#create-credential-definition-and-revocation-registry","title":"Create Credential Definition and Revocation Registry","text":"<p>An example of an Endorser flow is as follows, showing how a credential definition endorsement is received and processed, and optionally kicks off the revocation registry process:</p> <p></p> <p>You can see that there is a standard endorser flow happening each time there is a ledger write (illustrated in the \"Endorser\" process).</p> <p>At the end of each endorse sequence, the TransactionManager sends a notification via the EventBus so that any dependant processing can continue.  Each Router is responsible for listening and responding to these notifications if necessary.</p> <p>For example:</p> <ul> <li>Once the credential definition is created, a revocation registry must be created (for revocable cred defs)</li> <li>Once the revocation registry is created, a revocation entry must be created</li> <li>Potentially, the cred def status could be updated once the revocation entry is completed</li> </ul> <p>Using the EventBus decouples the event sequence.  Any functions triggered by an event notification are typically also available directly via Admin endpoints.</p>"},{"location":"features/Endorser/#create-did-and-promote-to-public","title":"Create DID and Promote to Public","text":"<p>... and an example of creating a DID and promoting it to public (and creating an ATTRIB for the endpoint:</p> <p></p> <p>You can see the same endorsement processes in this sequence.</p> <p>Once the DID is written, the DID can (optionally) be promoted to the public DID, which will also invoke an ATTRIB transaction to write the endpoint.</p>"},{"location":"features/JsonLdCredentials/","title":"JSON-LD Credentials in ACA-Py","text":"<p>By design Hyperledger Aries is credential format agnostic. This means you can use it for any credential format, as long as an RFC is defined for the specific credential format. ACA-Py currently supports two types of credentials, Indy and JSON-LD credentials. This document describes how to use the latter by making use of W3C Verifiable Credentials using Linked Data Proofs.</p>"},{"location":"features/JsonLdCredentials/#table-of-contents","title":"Table of Contents","text":"<ul> <li>General Concept</li> <li>BBS+</li> <li>Preparing to Issue a Credential</li> <li>JSON-LD Context<ul> <li>Writing JSON-LD Contexts</li> </ul> </li> <li>Signature Suite</li> <li>Did Method<ul> <li><code>did:sov</code></li> <li><code>did:key</code></li> </ul> </li> <li>Issuing Credentials</li> <li>Retrieving Issued Credentials</li> <li>Present Proof</li> <li>VC-API</li> </ul>"},{"location":"features/JsonLdCredentials/#general-concept","title":"General Concept","text":"<p>The rest of this guide assumes some basic understanding of W3C Verifiable Credentials, JSON-LD and Linked Data Proofs. If you're not familiar with some of these concepts, the following resources can help you get started:</p> <ul> <li>Verifiable Credentials Data Model</li> <li>JSON-LD Articles and Presentations</li> <li>Linked Data Proofs</li> </ul>"},{"location":"features/JsonLdCredentials/#bbs","title":"BBS+","text":"<p>BBS+ credentials offer a lot of privacy preserving features over non-ZKP credentials. Therefore we recommend to always use BBS+ credentials over non-ZKP credentials. To get started with BBS+ credentials it is recommended to at least read RFC 0646: W3C Credential Exchange using BBS+ Signatures for a general overview.</p> <p>Some other resources that can help you get started with BBS+ credentials:</p> <ul> <li>BBS+ Signatures 2020</li> <li>Video: BBS+ Credential Exchange in Hyperledger Aries</li> </ul>"},{"location":"features/JsonLdCredentials/#preparing-to-issue-a-credential","title":"Preparing to Issue a Credential","text":"<p>Contrary to Indy credentials, JSON-LD credentials do not need a schema or credential definition to issue credentials. Everything required to issue the credential is embedded into the credential itself using Linked Data Contexts.</p>"},{"location":"features/JsonLdCredentials/#json-ld-context","title":"JSON-LD Context","text":"<p>It is required that every property key in the document can be mapped to an IRI. This means the property key must either be an IRI by default, or have the shorthand property mapped in the <code>@context</code> of the document. If you have properties that are not mapped to IRIs, the Issue Credential API will throw the following error:</p> <p><code>&lt;x&gt; attributes dropped. Provide definitions in context to correct. [&lt;missing-properties&gt;]</code></p> <p>For credentials the <code>https://www.w3.org/2018/credentials/v1</code> context MUST always be the first context. In addition, when issuing BBS+ credentials the <code>https://w3id.org/security/bbs/v1</code> URL MUST be present in the context. For convenience this URL will be automatically added to the <code>@context</code> of the credential if not present.</p> <pre><code>{\n  \"@context\": [\n    \"https://www.w3.org/2018/credentials/v1\",\n    \"https://other-contexts.com\"\n  ]\n}\n</code></pre>"},{"location":"features/JsonLdCredentials/#writing-json-ld-contexts","title":"Writing JSON-LD Contexts","text":"<p>Writing JSON-LD contexts can be a daunting task and is out of scope of this guide. Generally you should try to make use of already existing vocabularies. Some examples are the vocabularies defined in the W3C Credentials Community Group:</p> <ul> <li>Vaccination Certificate Vocabulary</li> <li>Citizenship Vocabulary</li> <li>Traceability Vocabulary</li> </ul> <p>Verifiable credentials are not around that long, so there aren't that many vocabularies ready to use. If you can't use one of the existing vocabularies it is still beneficial to lean on already defined lower level contexts. http://schema.org has a large registry of definitions that can be used to build new contexts. The example vocabularies linked above all make use of types from http://schema.org.</p> <p>For the remainder of this guide, we will be using the example <code>UniversityDegreeCredential</code> type and <code>https://www.w3.org/2018/credentials/examples/v1</code> context from the Verifiable Credential Data Model. You should not use this for production use cases.</p>"},{"location":"features/JsonLdCredentials/#signature-suite","title":"Signature Suite","text":"<p>Before issuing a credential you must determine a signature suite to use. ACA-Py currently supports two signature suites for issuing credentials:</p> <ul> <li><code>Ed25519Signature2018</code> - Very well supported. No zero knowledge proofs or selective disclosure.</li> <li><code>BbsBlsSignature2020</code> - Newer, but supports zero knowledge proofs and selective disclosure.</li> </ul> <p>Generally you should always use <code>BbsBlsSignature2020</code> as it allows the holder to derive a new credential during the proving, meaning it doesn't have to disclose all fields and doesn't have to reveal the signature.</p>"},{"location":"features/JsonLdCredentials/#did-method","title":"Did Method","text":"<p>Besides the JSON-LD context, we need a did to use for issuing the credential. ACA-Py currently supports two did methods for issuing credentials:</p> <ul> <li><code>did:sov</code> - Can only be used for <code>Ed25519Signature2018</code> signature suite.</li> <li><code>did:key</code> - Can be used for both <code>Ed25519Signature2018</code> and <code>BbsBlsSignature2020</code> signature suites.</li> </ul>"},{"location":"features/JsonLdCredentials/#didsov","title":"<code>did:sov</code>","text":"<p>When using <code>did:sov</code> you need to make sure to use a public did so other agents can resolve the did. It is also important the other agent is using the same indy ledger for resolving the did. You can get the public did using the <code>/wallet/did/public</code> endpoint. For backwards compatibility the did is returned without <code>did:sov</code> prefix. When using the did for issuance make sure this prepend this to the did. (so <code>DViYrCMPWfuLiY7LLs8giB</code> becomes <code>did:sov:DViYrCMPWfuLiY7LLs8giB</code>)</p>"},{"location":"features/JsonLdCredentials/#didkey","title":"<code>did:key</code>","text":"<p>A <code>did:key</code> did is not anchored to a ledger, but embeds the key directly in the identifier part of the did. See the did:key Method Specification for more information.</p> <p>You can create a <code>did:key</code> using the <code>/wallet/did/create</code> endpoint with the following body. Use <code>ed25519</code> for <code>Ed25519Signature2018</code>, <code>bls12381g2</code> for <code>BbsBlsSignature2020</code>.</p> <pre><code>{\n  \"method\": \"key\",\n  \"options\": {\n    \"key_type\": \"bls12381g2\" // or ed25519\n  }\n}\n</code></pre> <p>The above call will return a did that looks something like this: <code>did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj</code></p>"},{"location":"features/JsonLdCredentials/#issuing-credentials","title":"Issuing Credentials","text":"<p>Issuing JSON-LD credentials is only possible with the issue credential v2 protocol (<code>/issue-credential-2.0</code>)</p> <p>The format used for exchanging JSON-LD credentials is defined in RFC 0593: JSON-LD Credential Attachment format. The API in ACA-Py exactly matches the formats as described in this RFC, with the most important (from the ACA-Py API perspective) being <code>aries/ld-proof-vc-detail@v1.0</code>. Read the RFC to see the exact properties required to construct a valid Linked Data Proof VC Detail.</p> <p>All endpoints in API use the <code>aries/ld-proof-vc-detail@v1.0</code>. We'll use the <code>/issue-credential-2.0/send</code> as an example, but it works the same for the other endpoints. In contrary to issuing indy credentials, JSON-LD credentials do not require a credential preview. All properties should be directly embedded in the credentials.</p> <p>The detail should be included under the <code>filter.ld_proof</code> property. To issue a credential call the <code>/issue-credential-2.0/send</code> endpoint, with the example body below and the <code>connection_id</code> and <code>issuer</code> keys replaced. The value of <code>issuer</code> should be the did that you created in the Did Method paragraph above.</p> <p>If you don't have <code>auto-respond-credential-offer</code> and <code>auto-store-credential</code> enabled in the ACA-Py config, you will need to call <code>/issue-credential-2.0/records/{cred_ex_id}/send-request</code> and <code>/issue-credential-2.0/records/{cred_ex_id}/store</code> to finalize the credential issuance.</p> See the example body <pre><code>{\n  \"connection_id\": \"ddc23de9-359f-465c-b66e-f7c5a0cc9a57\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"UniversityDegreeCredential\"],\n        \"issuer\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"features/JsonLdCredentials/#retrieving-issued-credentials","title":"Retrieving Issued Credentials","text":"<p>After issuing the credential, the credentials should be stored inside the wallet. Because the structure of JSON-LD credentials is so different from indy credentials a new endpoint is added to retrieve W3C credentials.</p> <p>Call the <code>/credentials/w3c</code> endpoint to retrieve all JSON-LD credentials in your wallet. See the detail below for an example response based on the issued credential from the Issuing Credentials paragraph above.</p> See the example response <pre><code>{\n  \"results\": [\n    {\n      \"contexts\": [\n        \"https://www.w3.org/2018/credentials/examples/v1\",\n        \"https://www.w3.org/2018/credentials/v1\",\n        \"https://w3id.org/security/bbs/v1\"\n      ],\n      \"types\": [\"UniversityDegreeCredential\", \"VerifiableCredential\"],\n      \"schema_ids\": [],\n      \"issuer_id\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n      \"subject_ids\": [],\n      \"proof_types\": [\"BbsBlsSignature2020\"],\n      \"cred_value\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\",\n          \"https://w3id.org/security/bbs/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"UniversityDegreeCredential\"],\n        \"issuer\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        },\n        \"proof\": {\n          \"type\": \"BbsBlsSignature2020\",\n          \"proofPurpose\": \"assertionMethod\",\n          \"verificationMethod\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj#zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n          \"created\": \"2021-05-03T12:31:28.561945\",\n          \"proofValue\": \"iUFtRGdLLCWxKx8VD3oiFBoRMUFKhSitTzMsfImXm6OF0d8il+Z40aLz8S7m8EcXPQhRjcWWL9jkfcf1SDifD4CvxVg69NvB7hZyIIz9hwAyi3LmTm0ez4NDRCKyieBuzqKbfM2eACWn/ilhOJBm6w==\"\n        }\n      },\n      \"cred_tags\": {},\n      \"record_id\": \"541ddbce5760497d98e68917be8c05bd\"\n    }\n  ]\n}\n</code></pre>"},{"location":"features/JsonLdCredentials/#present-proof","title":"Present Proof","text":"<p>\u26a0\ufe0f TODO: https://github.com/hyperledger/aries-cloudagent-python/pull/1125</p>"},{"location":"features/JsonLdCredentials/#vc-api","title":"VC-API","text":"<p>In order to support these functions outside of the respective DIDComm protocols, a set of endpoints conforming to the vc-api specification are available. These endpoints should be used by a controller when building an identity platform.</p> <p>These endpoints include:</p> <ul> <li><code>GET /vc/credentials</code> -&gt; returns a list of all stored json-ld credentials</li> <li><code>GET /vc/credentials/{id}</code> -&gt; returns a json-ld credential based on it's ID</li> <li><code>POST /vc/credentials/issue</code> -&gt; signs a credential</li> <li><code>POST /vc/credentials/verify</code> -&gt; verifies a credential</li> <li><code>POST /vc/credentials/store</code> -&gt; stores an issued credential</li> <li><code>POST /vc/presentations/prove</code> -&gt; proves a presentation</li> <li><code>POST /vc/presentations/verify</code> -&gt; verifies a presentation</li> </ul> <p>To learn more about using these endpoints, please refer to the available postman collection.</p>"},{"location":"features/Mediation/","title":"Mediation docs","text":""},{"location":"features/Mediation/#concepts","title":"Concepts","text":"<ul> <li>DIDComm Message Forwarding - Sending an encrypted message to its recipient by first sending it to a third party responsible for forwarding the message on. Message contents are encrypted once for the recipient then wrapped in a forward message encrypted to the third party.</li> <li>Mediator - An agent that forwards messages to a client over a DIDComm connection.</li> <li>Mediated Agent or Mediation client - The agent(s) to which a mediator is willing to forward messages.</li> <li>Mediation Request - A message from a client to a mediator requesting mediation or forwarding.</li> <li>Keylist - The list of public keys used by the mediator to lookup to which connection a forward message should be sent. Each mediated agent is responsible for maintaining the keylist with the mediator.</li> <li>Keylist Update - A message from a client to a mediator informing the mediator of changes to the keylist.</li> <li>Default Mediator - A mediator to be used with every newly created DIDComm connection.</li> <li>Mediation Connection - Connection between the mediator and the mediated agent or client. Agents can use as many mediators as the identity owner sees fit. Requests for mediation are handled on a per connection basis.</li> <li>See Aries RFC 0211: Coordinate Mediation Protocol for additional details on message attributes and more.</li> </ul>"},{"location":"features/Mediation/#command-line-arguments","title":"Command Line Arguments","text":"<ul> <li><code>--open-mediation</code> - Instructs mediators to automatically grant all incoming mediation requests.</li> <li><code>--mediator-invitation</code> - Receive invitation, send mediation request and set as default mediator.</li> <li><code>--mediator-connections-invite</code> - Connect to mediator through a connection invitation. If not specified, connect using an OOB invitation.</li> <li><code>--default-mediator-id</code> - Set pre-existing mediator as default mediator.</li> <li><code>--clear-default-mediator</code> - Clear the stored default mediator.</li> </ul> <p>The minimum set of arguments required to enable mediation are:</p> <pre><code>aca-py start ... \\\n    --open-mediation\n</code></pre> <p>To automate the mediation process on startup, additionally specify the following argument on the mediated agent (not the mediator):</p> <pre><code>aca-py start ... \\\n    --mediator-invitation \"&lt;a multi-use invitation url from the mediator&gt;\"\n</code></pre> <p>If a default mediator has already been established, then the <code>--default-mediator-id</code> argument can be used instead of the <code>--mediator-invitation</code>.</p>"},{"location":"features/Mediation/#didcomm-messages","title":"DIDComm Messages","text":"<p>See Aries RFC 0211: Coordinate Mediation Protocol.</p>"},{"location":"features/Mediation/#admin-api","title":"Admin API","text":"<ul> <li><code>GET mediation/requests</code></li> <li>Return a list of all mediation records. Filter by <code>conn_id</code>, <code>state</code>, <code>mediator_terms</code> and <code>recipient_terms</code>.</li> <li><code>GET mediation/requests/{mediation_id}</code></li> <li>Retrieve a mediation record by id.</li> <li><code>DELETE mediation/requests/{mediation_id}</code></li> <li>Delete mediation record by id.</li> <li><code>POST mediation/requests/{mediation_id}/grant</code></li> <li>As a mediator, grant a stored mediation request and send <code>granted</code> message to client.</li> <li><code>POST mediation/requests/{mediation_id}/deny</code></li> <li>As a mediator, deny a stored mediation request and send <code>denied</code> message to client.</li> <li><code>POST mediation/request/{conn_id}</code></li> <li>Send a mediation request to connection identified by the given connection ID.</li> <li><code>GET mediation/keylists</code></li> <li>Returns key list associated with a connection. Filter on <code>client</code> for keys mediated by other agents and <code>server</code> for keys mediated by this agent.</li> <li><code>POST mediation/keylists/{mediation_id}/send-keylist-update</code></li> <li>Send keylist update message to mediator identified by the given mediation ID. Updates contained in body of request.</li> <li><code>POST mediation/keylists/{mediation_id}/send-keylist-query</code></li> <li>Send keylist query message to mediator identified by the given mediation ID.</li> <li><code>GET mediation/default-mediator</code> (PR pending)</li> <li>Retrieve the currently set default mediator.</li> <li><code>PUT mediation/{mediation_id}/default-mediator</code> (PR pending)</li> <li>Set the mediator identified by the given mediation ID as the default mediator.</li> <li><code>DELETE mediation/default-mediator</code> (PR pending)</li> <li>Clear the currently set default mediator (mediation status is maintained and remains functional, just not used as the default).</li> </ul>"},{"location":"features/Mediation/#mediator-message-flow-overview","title":"Mediator Message Flow Overview","text":""},{"location":"features/Mediation/#using-a-mediator","title":"Using a Mediator","text":"<p>After establishing a connection with a mediator also having mediation granted, you can use that mediator id for future did_comm connections.  When creating, receiving or accepting an invitation intended to be Mediated, you provide <code>mediation_id</code> with the desired mediator id. if using a single mediator for all future connections, You can set a default mediation id. If no mediation_id is provided the default mediation id will be used instead.</p>"},{"location":"features/Multicredentials/","title":"Multi-Credentials","text":"<p>It is a known fact that multiple AnonCreds can be combined to present a presentation proof with an \"and\" logical operator: For instance, a verifier can ask for the \"name\" claim from an eID and the \"address\" claim from a bank statement to have a single proof that is either valid or invalid. With the Present Proof Protocol v2, it is possible to have \"and\" and \"or\" logical operators for AnonCreds and/or W3C Verifiable Credentials.</p> <p>With the Present Proof Protocol v2, verifiers can ask for a combination of credentials as proof. For instance, a Verifier can ask a claim from an AnonCreds and a verifiable presentation from a W3C Verifiable Credential, which would open the possibilities of Aries Cloud Agent Python being used for rather complex presentation proof requests that wouldn't be possible without the support of AnonCreds or W3C Verifiable Credentials.</p> <p>Moreover, it is possible to make similar presentation proof requests using the or logical operator. For instance, a verifier can ask for either an eID in AnonCreds format or an eID in W3C Verifiable Credential format. This has the potential to solve the interoperability problem of different credential formats and ecosystems from a user point of view by shifting the requirement of holding/accepting different credential formats from identity holders to verifiers. Here again, using Aries Cloud Agent Python as the underlying verifier agent can tackle such complex presentation proof requests since the agent is capable of verifying both type of credential formats and proof types.</p> <p>In the future, it would be even possible to put mDoc as an attachment with an and or or logical operation, along with AnonCreds and/or W3C Verifiable Credentials. For this to happen, Aca-Py either needs the capabilities to validate mDocs internally or to connect third-party endpoints to validate and get a response.</p>"},{"location":"features/Multiledger/","title":"Multi-ledger in ACA-Py","text":"<p>Ability to use multiple Indy ledgers (both IndySdk and IndyVdr) for resolving a <code>DID</code> by the ACA-Py agent. For read requests, checking of multiple ledgers in parallel is done dynamically according to logic detailed in Read Requests Ledger Selection. For write requests, dynamic allocation of <code>write_ledger</code> is supported. Configurable write ledgers can be assigned using <code>is_write</code> in the configuration or using any of the <code>--genesis-url</code>, <code>--genesis-file</code>, and <code>--genesis-transactions</code> startup (ACA-Py) arguments. If no write ledger is assigned then a <code>ConfigError</code> is raised.</p> <p>More background information including problem statement, design (algorithm) and more can be found here.</p>"},{"location":"features/Multiledger/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Usage</li> <li>Example config file</li> <li>Config properties</li> <li>Multi-ledger Admin API</li> <li>Ledger Selection</li> <li>Read Requests<ul> <li>For checking ledger in parallel</li> </ul> </li> <li>Write Requests</li> <li>A Special Warning for TAA Acceptance</li> <li>Impact on other ACA-Py function</li> <li>Known Issues</li> </ul>"},{"location":"features/Multiledger/#usage","title":"Usage","text":"<p>Multi-ledger is disabled by default. You can enable support for multiple ledgers using the <code>--genesis-transactions-list</code> startup parameter. This parameter accepts a string which is the path to the <code>YAML</code> configuration file. For example:</p> <p><code>--genesis-transactions-list ./aries_cloudagent/config/multi_ledger_config.yml</code></p> <p>If <code>--genesis-transactions-list</code> is specified, then <code>--genesis-url, --genesis-file, --genesis-transactions</code> should not be specified.</p>"},{"location":"features/Multiledger/#example-config-file","title":"Example config file","text":"<pre><code>- id: localVON\n  is_production: false\n  genesis_url: 'http://host.docker.internal:9000/genesis'\n- id: bcovrinTest\n  is_production: true\n  is_write: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n</code></pre> <pre><code>- id: localVON\n  is_production: false\n  genesis_url: 'http://host.docker.internal:9000/genesis'\n- id: bcovrinTest\n  is_production: true\n  is_write: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n  endorser_did: '9QPa6tHvBHttLg6U4xvviv'\n  endorser_alias: 'endorser_test'\n- id: greenlightDev\n  is_production: true\n  is_write: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n</code></pre> <p>Note: <code>is_write</code> property means that the ledger is write configurable. With reference to the above config example, both <code>bcovrinTest</code> and (the no longer available -- in the above its pointing to BCovrin Test as well) <code>greenlightDev</code> ledgers are write configurable. By default, on startup <code>bcovrinTest</code> will be the write ledger as it is the topmost write configurable production ledger, more details regarding the selection rule. Using <code>PUT /ledger/{ledger_id}/set-write-ledger</code> endpoint, either <code>greenlightDev</code> and <code>bcovrinTest</code> can be set as the write ledger.</p> <p>Note 2: The <code>greenlightDev</code> ledger is no longer available, so both ledger entries in the example above and below intentionally point to the same ledger URL.</p> <pre><code>- id: localVON\n  is_production: false\n  is_write: true\n  genesis_url: 'http://host.docker.internal:9000/genesis'\n- id: bcovrinTest\n  is_production: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n- id: greenlightDev\n  is_production: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n</code></pre> <p>Note: For instance with regards to example config above, <code>localVON</code> will be the write ledger, as there are no production ledgers which are configurable it will choose the topmost write configurable non production ledger.</p>"},{"location":"features/Multiledger/#config-properties","title":"Config properties","text":"<p>For each ledger, the required properties are as following:</p> <ul> <li><code>id</code>*: The id (or name) of the ledger, can also be used as the pool name if none provided</li> <li><code>is_production</code>*: Whether the ledger is a production ledger. This is used by the pool selector algorithm to know which ledger to use for certain interactions (i.e. prefer production ledgers over non-production ledgers)</li> </ul> <p>For connecting to ledger, one of the following needs to be specified:</p> <ul> <li><code>genesis_file</code>: The path to the genesis file to use for connecting to an Indy ledger.</li> <li><code>genesis_transactions</code>: String of genesis transactions to use for connecting to an Indy ledger.</li> <li><code>genesis_url</code>: The url from which to download the genesis transactions to use for connecting to an Indy ledger.</li> </ul> <p>Optional properties:</p> <ul> <li><code>pool_name</code>: name of the indy pool to be opened</li> <li><code>keepalive</code>: how many seconds to keep the ledger open</li> <li><code>socks_proxy</code></li> <li><code>is_write</code>: Whether this ledger is writable. It requires at least one write ledger specified. Multiple write ledgers can be specified in config.</li> <li><code>endorser_did</code>: Endorser public DID registered on the ledger, needed for supporting Endorser protocol at multi-ledger level.</li> <li><code>endorser_alias</code>: Endorser alias for this ledger, needed for supporting Endorser protocol at multi-ledger level.</li> </ul> <p>Note: Both <code>endorser_did</code> and <code>endorser_alias</code> are part of the endorser info. Whenever a write ledger is selected using <code>PUT /ledger/{ledger_id}/set-write-ledger</code>, the endorser info associated with that ledger in the config updates the <code>endorser.endorser_public_did</code> and <code>endorser.endorser_alias</code> profile setting respectively.</p>"},{"location":"features/Multiledger/#multi-ledger-admin-api","title":"Multi-ledger Admin API","text":"<p>Multi-ledger related actions are grouped under the <code>ledger</code> topic in the SwaggerUI.</p> <ul> <li>GET <code>/ledger/config</code>: Returns the multiple ledger configuration currently in use</li> <li>GET <code>/ledger/get-write-ledger</code>: Returns the current active/set <code>write_ledger's</code> <code>ledger_id</code></li> <li>GET <code>/ledger/get-write-ledgers</code>: Returns list of available <code>write_ledger's</code> <code>ledger_id</code></li> <li>PUT <code>/ledger/{ledger_id}/set-write-ledger</code>: Set active <code>write_ledger's</code> <code>ledger_id</code></li> </ul>"},{"location":"features/Multiledger/#ledger-selection","title":"Ledger Selection","text":""},{"location":"features/Multiledger/#read-requests","title":"Read Requests","text":"<p>The following process is executed for these functions in ACA-Py:</p> <ol> <li><code>get_schema</code></li> <li><code>get_credential_definition</code></li> <li><code>get_revoc_reg_def</code></li> <li><code>get_revoc_reg_entry</code></li> <li><code>get_key_for_did</code></li> <li><code>get_all_endpoints_for_did</code></li> <li><code>get_endpoint_for_did</code></li> <li><code>get_nym_role</code></li> <li><code>get_revoc_reg_delta</code></li> </ol> <p>If multiple ledgers are configured then <code>IndyLedgerRequestsExecutor</code> service extracts <code>DID</code> from the record identifier and executes the check below, else it returns the <code>BaseLedger</code> instance.</p>"},{"location":"features/Multiledger/#for-checking-ledger-in-parallel","title":"For checking ledger in parallel","text":"<ul> <li><code>lookup_did_in_configured_ledgers</code> function</li> <li>If the calling function (above) is in items 1-4, then check the <code>DID</code> in <code>cache</code> for a corresponding applicable <code>ledger_id</code>. If found, return the ledger info, else continue.</li> <li>Otherwise, launch parallel <code>_get_ledger_by_did</code> tasks for each of the configured ledgers.</li> <li>As these tasks get finished, construct <code>applicable_prod_ledgers</code> and <code>applicable_non_prod_ledgers</code> dictionaries, each with <code>self_certified</code> and <code>non_self_certified</code> inner dict which are sorted by the original order or index.</li> <li>Order/preference for selection: <code>self_certified</code> &gt; <code>production</code> &gt; <code>non_production</code><ul> <li>Checks <code>production</code> ledger where the <code>DID</code> is <code>self_certified</code></li> <li>Checks <code>non_production</code> ledger where the <code>DID</code> is <code>self_certified</code></li> <li>Checks <code>production</code> ledger where the <code>DID</code> is not <code>self_certified</code></li> <li>Checks <code>non_production</code> ledger where the <code>DID</code> is not <code>self_certified</code></li> </ul> </li> <li>Return an applicable ledger if found, else raise an exception.</li> <li><code>_get_ledger_by_did</code> function</li> <li>Build and submit <code>GET_NYM</code></li> <li>Wait for a response for 10 seconds, if timed out return None</li> <li>Parse response</li> <li>Validate state proof</li> <li>Check if <code>DID</code> is self certified</li> <li>Returns ledger info to <code>lookup_did_in_configured_ledgers</code></li> </ul>"},{"location":"features/Multiledger/#write-requests","title":"Write Requests","text":"<p>On startup, the first configured applicable ledger is assigned as the <code>write_ledger</code> (<code>BaseLedger</code>), the selection is dependent on the order (top-down) and whether it is <code>production</code> or <code>non_production</code>. For instance, considering this example configuration, ledger <code>bcovrinTest</code> will be set as <code>write_ledger</code> as it is the topmost <code>production</code> ledger. If no <code>production</code> ledgers are included in configuration then the topmost <code>non_production</code> ledger is selected.</p>"},{"location":"features/Multiledger/#a-special-warning-for-taa-acceptance","title":"A Special Warning for TAA Acceptance","text":"<p>When you run in multi-ledger mode, ACA-Py will use the <code>pool-name</code> (or <code>id</code>) specified in the ledger configuration file for each ledger.</p> <p>(When running in single-ledger mode, ACA-Py uses <code>default</code> as the ledger name.)</p> <p>If you are running against a ledger in <code>write</code> mode, and the ledger requires you to accept a Transaction Author Agreement (TAA), ACA-Py stores the TAA acceptance status in the wallet in a non-secrets record, using the ledger's <code>pool_name</code> as a key.</p> <p>This means that if you are upgrading from single-ledger to multi-ledger mode, you will need to either:</p> <ul> <li>set the <code>id</code> for your writable ledger to <code>default</code> (in your <code>ledgers.yaml</code> file)</li> </ul> <p>or:</p> <ul> <li>re-accept the TAA once you restart your ACA-Py in multi-ledger mode</li> </ul> <p>Once you re-start ACA-Py, you can check the <code>GET /ledger/taa</code> endpoint to verify your TAA acceptance status.</p>"},{"location":"features/Multiledger/#impact-on-other-aca-py-function","title":"Impact on other ACA-Py function","text":"<p>There should be no impact/change in functionality to any ACA-Py protocols.</p> <p><code>IndySdkLedger</code> was refactored by replacing <code>wallet: IndySdkWallet</code> instance variable with <code>profile: Profile</code> and accordingly <code>.aries_cloudagent/indy/credex/verifier</code>, <code>.aries_cloudagent/indy/models/pres_preview</code>, <code>.aries_cloudagent/indy/sdk/profile.py</code>, <code>.aries_cloudagent/indy/sdk/verifier</code>, <code>./aries_cloudagent/indy/verifier</code> were also updated.</p> <p>Added <code>build_and_return_get_nym_request</code> and <code>submit_get_nym_request</code> helper functions to <code>IndySdkLedger</code> and <code>IndyVdrLedger</code>.</p> <p>Best practice/feedback emerging from <code>Askar session deadlock</code> issue and <code>endorser refactoring</code> PR was also addressed here by not leaving sessions open unnecessarily and changing <code>context.session</code> to <code>context.profile.session</code>, etc.</p> <p>These changes are made here:</p> <ul> <li><code>./aries_cloudagent/ledger/routes.py</code></li> <li><code>./aries_cloudagent/messaging/credential_definitions/routes.py</code></li> <li><code>./aries_cloudagent/messaging/schemas/routes.py</code></li> <li><code>./aries_cloudagent/protocols/actionmenu/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/actionmenu/v1_0/util.py</code></li> <li><code>./aries_cloudagent/protocols/basicmessage/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/coordinate_mediation/v1_0/handlers/keylist_handler.py</code></li> <li><code>./aries_cloudagent/protocols/coordinate_mediation/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/endorse_transaction/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/introduction/v0_1/handlers/invitation_handler.py</code></li> <li><code>./aries_cloudagent/protocols/introduction/v0_1/routes.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_issue_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_offer_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_proposal_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_request_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v2_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/handlers/presentation_handler.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/handlers/presentation_proposal_handler.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/handlers/presentation_request_handler.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/trustping/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/resolver/routes.py</code></li> <li><code>./aries_cloudagent/revocation/routes.py</code></li> </ul>"},{"location":"features/Multiledger/#known-issues","title":"Known Issues","text":"<ul> <li>When in multi-ledger mode and switching ledgers (e.g.: the agent is registered on Ledger A and has published its DID there, and now wants to \"move\" to Ledger B) there is an issue that will cause the registration to the new ledger to fail.</li> </ul>"},{"location":"features/Multitenancy/","title":"Multi-tenancy in ACA-Py","text":"<p>Most deployments of ACA-Py use a single wallet for all operations. This means all connections, credentials, keys, and everything else is stored in the same wallet and shared between all controllers of the agent. Multi-tenancy in ACA-Py allows multiple tenants to use the same ACA-Py instance with a different context. All tenants get their own encrypted wallet that only holds their own data.</p> <p>This allows ACA-Py to be used for a wider range of use cases. One use case could be a company that creates a wallet for each department. Each department has full control over the actions they perform while having a shared instance for easy maintenance. Another use case could be for a Issuer-Hosted Custodial Agent. Sometimes it is required to host the agent on behalf of someone else.</p>"},{"location":"features/Multitenancy/#table-of-contents","title":"Table of Contents","text":"<ul> <li>General Concept</li> <li>Base and Sub Wallets</li> <li>Usage</li> <li>Multi-tenant Admin API</li> <li>Managed vs Unmanaged Mode</li> <li>Managed Mode</li> <li>Unmanaged Mode</li> <li>Mode Usage</li> <li>Message Routing</li> <li>Relaying</li> <li>Mediation</li> <li>Webhooks</li> <li>Webhook URLs</li> <li>Identifying the wallet</li> <li>Authentication</li> <li>Getting a token<ul> <li>Method 1: Register new tenant</li> <li>Method 2: Get tenant token</li> </ul> </li> <li>JWT Secret</li> <li>SwaggerUI</li> <li>Tenant Management</li> <li>Update a tenant</li> <li>Remove a tenant</li> <li>Per tenant settings</li> </ul>"},{"location":"features/Multitenancy/#general-concept","title":"General Concept","text":"<p>When multi-tenancy is enabled in ACA-Py there is still a single agent running, however, some of the resources are now shared between the tenants of the agent. Each tenant has their own wallet, with their own DIDs, connections, and credentials. Transports and most of the settings are still shared between agents. Each wallet uses the same endpoint, so to the outside world, it is not obvious multiple tenants are using the same agent.</p>"},{"location":"features/Multitenancy/#base-and-sub-wallets","title":"Base and Sub Wallets","text":"<p>Multi-tenancy in ACA-Py makes a distinction between a base wallet and sub wallets.</p> <p>The wallets used by the different tenants are called sub wallets. A sub wallet is almost identical to a wallet when multi-tenancy is disabled. This means that you can do everything with it that a single-tenant ACA-Py instance can also do.</p> <p>The base wallet however, takes on a different role and has limited functionality. Its main function is to manage the sub wallets, which can be done using the Multi-tenant Admin API. It stores all settings and information about the different sub wallets and will route incoming messages to the corresponding sub wallets. See Message Routing for more details. All other features are disabled for the base wallet. This means it cannot issue credentials, present proof, or do any of the other actions sub wallets can do. This is to keep a clear hierarchical difference between base and sub wallets. For this reason, the base wallet should generally not be provisioned using the <code>--wallet-seed</code> argument as not only it is not necessary for sub wallet management operations, but it will also require this DID to be correctly registered on the ledger for the service to start-up correctly.</p> <p></p>"},{"location":"features/Multitenancy/#usage","title":"Usage","text":"<p>Multi-tenancy is disabled by default. You can enable support for multiple wallets using the <code>--multitenant</code> startup parameter. To also be able to manage wallets for the tenants, the multi-tenant admin API can be enabled using the <code>--multitenant-admin</code> startup parameter. See Multi-tenant Admin API below for more info on the admin API.</p> <p>The <code>--jwt-secret</code> startup parameter is required when multi-tenancy is enabled. This is used for JWT creation and verification. See Authentication below for more info.</p> <p>Example:</p> <pre><code># This enables multi-tenancy in ACA-Py\nmultitenant: true\n\n# This enables the admin API for multi-tenancy. More information below\nmultitenant-admin: true\n\n# This sets the secret used for JWT creation/verification for sub wallets\njwt-secret: Something very secret\n</code></pre>"},{"location":"features/Multitenancy/#multi-tenant-admin-api","title":"Multi-tenant Admin API","text":"<p>The multi-tenant admin API allows you to manage wallets in ACA-Py. Only the base wallet can manage wallets, so you can't for example create a wallet in the context of sub wallet (using the <code>Authorization</code> header as specified in Authentication).</p> <p>Multi-tenancy related actions are grouped under the <code>/multitenancy</code> path or the <code>multitenancy</code> topic in the SwaggerUI. As mentioned above, the multi-tenant admin API is disabled by default, event when multi-tenancy is enabled. This is to allow for more flexible agent configuration (e.g. horizontal scaling where only a single instance exposes the admin API). To enable the multi-tenant admin API, the <code>--multitenant-admin</code> startup parameter can be used.</p> <p>See the SwaggerUI for the exact API definition for multi-tenancy.</p>"},{"location":"features/Multitenancy/#managed-vs-unmanaged-mode","title":"Managed vs Unmanaged Mode","text":"<p>Multi-tenancy in ACA-Py is designed with two key management modes in mind.</p>"},{"location":"features/Multitenancy/#managed-mode","title":"Managed Mode","text":"<p>In <code>managed</code> mode, ACA-Py will manage the key for the wallet. This is the easiest configuration as it allows ACA-Py to fully control the wallet. When a message is received from another agent it can immediately unlock the wallet and process the message. The wallet key is stored encrypted in the base wallet.</p>"},{"location":"features/Multitenancy/#unmanaged-mode","title":"Unmanaged Mode","text":"<p>In <code>unmanaged</code> mode, ACA-Py won't manage the key for the wallet. The key is not stored in the base wallet, which means the key to unlock the wallet needs to be provided whenever the wallet is used. When a message from another agent is received, ACA-Py cannot immediately unlock the wallet and process the message. See Authentication for more info.</p> <p>It is important to note unmanaged mode doesn't provide a lot of security over managed mode. The key is still processed by the agent, and therefore trust is required. It could however provide some benefit in the case a multi-tenant agent is compromised, as the agent doesn't store the key to unlock the wallet.</p> <p> Although support for unmanaged mode is mostly in place, the receiving of messages from other agents in unmanaged mode is not supported yet. This means unmanaged mode can not be used yet.</p>"},{"location":"features/Multitenancy/#mode-usage","title":"Mode Usage","text":"<p>The mode used can be specified when creating a wallet using the <code>key_management_mode</code> parameter.</p> <pre><code>// POST /multitenancy/wallet\n{\n  // ... other params ...\n  \"key_management_mode\": \"managed\" // or \"unmanaged\"\n}\n</code></pre>"},{"location":"features/Multitenancy/#message-routing","title":"Message Routing","text":"<p>In multi-tenant mode, when ACA-Py receives a message from another agent, it will need to determine which tenant to route the message to. Hyperledger Aries defines two types of routing methods, mediation and relaying.</p> <p>See the Mediators and Relays RFC for an in-depth description of the difference between the two concepts.</p>"},{"location":"features/Multitenancy/#relaying","title":"Relaying","text":"<p>In multi-tenant mode, ACA-Py still exposes a single endpoint for each transport. This means it can't route messages to sub wallets based on the endpoint. To resolve this the base wallet acts as a relay for all sub wallets. As can be seen in the architecture diagram above, all messages go through the base wallet. whenever a sub wallet creates a new key or connection, it will be registered at the base wallet. This allows the base wallet to look at the recipient keys for a message and determine which wallet it needs to route to.</p>"},{"location":"features/Multitenancy/#mediation","title":"Mediation","text":"<p>ACA-Py allows messages to be routed through a mediator, and multi-tenancy can be used in combination with external mediators. The following scenarios are possible:</p> <ol> <li>The base wallet has a default mediator set that will be used by sub wallets.</li> <li>Use <code>--mediator-invitation</code> to connect to the mediator, request mediation, and set it as the default mediator</li> <li>Use <code>default-mediator-id</code> if you're already connected to the mediator and mediation is granted (e.g. after restart).</li> <li>When a sub wallet creates a connection or key it will be registered at the mediator via the base wallet connection. The base wallet will still act as a relay and route the messages to the correct sub wallets.</li> <li>Pro: Not every wallet needs to create a connection with the mediator</li> <li>Con: Sub wallets have no control over the mediator.</li> <li>Sub wallet creates a connection with mediator and requests mediation</li> <li>Use mediation as you would in a non-multi-tenant agent, however, the base wallet will still act as a relay.</li> <li>You can set the default mediator to use for connections (using the mediation API).</li> <li>Pro: Sub wallets have control over the mediator.</li> <li>Con: Every wallet</li> </ol> <p>The main tradeoff between option 1. and 2. is redundancy and control. Option 1. doesn't require every sub wallet to create a new connection with the mediator and request mediation. When all sub wallets are going to use the same mediator, this can be a huge benefit. Option 2. gives more control over the mediator being used. This could be useful if e.g. all wallets use a different mediator.</p> <p>A combination of option 1. and 2. is also possible. In this case, two mediators will be used and the sub wallet mediator will forward to the base wallet mediator, which will, in turn, forward to the ACA-Py instance.</p> <pre><code>+---------------------+      +----------------------+      +--------------------+\n| Sub wallet mediator | ---&gt; | Base wallet mediator | ---&gt; | Multi-tenant agent |\n+---------------------+      +----------------------+      +--------------------+\n</code></pre>"},{"location":"features/Multitenancy/#webhooks","title":"Webhooks","text":""},{"location":"features/Multitenancy/#webhook-urls","title":"Webhook URLs","text":"<p>ACA-Py makes use of webhook events to call back to the controller. Multiple webhook targets can be specified, however, in multi-tenant mode, it may be desirable to specify different webhook targets per wallet.</p> <p>When creating a wallet <code>wallet_dispatch_type</code> be used to specify how webhooks for the wallet should be dispatched. The options are:</p> <ul> <li><code>default</code>: Dispatch only to webhooks associated with this wallet.</li> <li><code>base</code>: Dispatch only to webhooks associated with the base wallet.</li> <li><code>both</code>: Dispatch to both webhook targets.</li> </ul> <p>If either <code>default</code> or <code>both</code> is specified you can set the webhook URLs specific to this wallet using the <code>wallet.webhook_urls</code> option.</p> <p>Example:</p> <pre><code>// POST /multitenancy/wallet\n{\n  // ... other params ...\n  \"wallet_dispatch_type\": \"default\",\n  \"wallet_webhook_urls\": [\n    \"https://webhook-url.com/path\",\n    \"https://another-url.com/site\"\n  ]\n}\n</code></pre>"},{"location":"features/Multitenancy/#identifying-the-wallet","title":"Identifying the wallet","text":"<p>When the webhook URLs of the base wallet are used or when multiple wallets specify the same webhook URL it can be hard to identify the wallet an event belongs to. To resolve this each webhook event will include the wallet id the event corresponds to.</p> <p>For HTTP events the wallet id is included as the <code>x-wallet-id</code> header. For WebSockets, the wallet id is included in the enclosing JSON object.</p> <p>HTTP example:</p> <pre><code>POST &lt;webhook-url&gt;/{topic} [headers=x-wallet-id]\n{\n    // event payload\n}\n</code></pre> <p>WebSocket example:</p> <pre><code>{\n  \"topic\": \"{topic}\",\n  \"wallet_id\": \"{wallet_id}\",\n  \"payload\": {\n    // event payload\n  }\n}\n</code></pre>"},{"location":"features/Multitenancy/#authentication","title":"Authentication","text":"<p>When multi-tenancy is not enabled you can authenticate with the agent using the <code>x-api-key</code> header. As there is only a single wallet, this provides sufficient authentication and authorization.</p> <p>For sub wallets, an additional authentication method is introduced using JSON Web Tokens (JWTs). A <code>token</code> parameter is returned after creating a wallet or calling the get token endpoint. This token must be provided for every admin API call you want to perform for the wallet using the Bearer authorization scheme.</p> <p>Example</p> <pre><code>GET /connections [headers=\"Authorization: Bearer {token}]\n</code></pre> <p>The <code>Authorization</code> header is in addition to the Admin API key. So if the <code>admin-api-key</code> is enabled (which should be enabled in production) both the <code>Authorization</code> and the <code>x-api-key</code> headers should be provided when making calls to a sub wallet. For calls to a base wallet, only the <code>x-api-key</code> should be provided.</p>"},{"location":"features/Multitenancy/#getting-a-token","title":"Getting a token","text":"<p>A token can be obtained in two ways. The first method is the <code>token</code> parameter from the response of the create wallet (<code>POST /multitenancy/wallet</code>) endpoint. The second option is using the get wallet token endpoint (<code>POST /multitenancy/wallet/{wallet_id}/token</code>) endpoint.</p>"},{"location":"features/Multitenancy/#method-1-register-new-tenant","title":"Method 1: Register new tenant","text":"<p>This is the method you use to obtain a token when you haven't already registered a tenant.  In this process you will first register a tenant then an object containing your tenant <code>token</code> as well as other useful information like your <code>wallet id</code> will be returned to you.</p> <p>Example</p> <pre><code>new_tenant='{\n  \"image_url\": \"https://aries.ca/images/sample.png\",\n  \"key_management_mode\": \"managed\",\n  \"label\": \"example-label-02\",\n  \"wallet_dispatch_type\": \"default\",\n  \"wallet_key\": \"example-encryption-key-02\",\n  \"wallet_name\": \"example-name-02\",\n  \"wallet_type\": \"askar\",\n  \"wallet_webhook_urls\": [\n    \"https://example.com/webhook\"\n  ]\n}'\n</code></pre> <pre><code>echo $new_tenant | curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"X-Api-Key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d @-\n</code></pre> <p><code>Response</code></p> <pre><code>{\n  \"settings\": {\n    \"wallet.type\": \"askar\",\n    \"wallet.name\": \"example-name-02\",\n    \"wallet.webhook_urls\": [\n      \"https://example.com/webhook\"\n    ],\n    \"wallet.dispatch_type\": \"default\",\n    \"default_label\": \"example-label-02\",\n    \"image_url\": \"https://aries.ca/images/sample.png\",\n    \"wallet.id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\"\n  },\n  \"key_management_mode\": \"managed\",\n  \"updated_at\": \"2022-04-01T15:12:35.474975Z\",\n  \"wallet_id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\",\n  \"created_at\": \"2022-04-01T15:12:35.474975Z\",\n  \"token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ3YWxsZXRfaWQiOiIzYjY0YWQwZC1mNTU2LTRjMDQtOTJiYy1jZDk1YmZkZTU4Y2QifQ.A4eWbSR2M1Z6mbjcSLOlciBuUejehLyytCVyeUlxI0E\"\n}\n</code></pre>"},{"location":"features/Multitenancy/#method-2-get-tenant-token","title":"Method 2: Get tenant token","text":"<p>This method allows you to retrieve a tenant <code>token</code> for an already registered tenant.  To retrieve a token you will need an Admin API key (if your admin is protected with one), <code>wallet_key</code> and the <code>wallet_id</code> of the tenant. Note that calling the get tenant token endpoint will invalidate the old token. This is useful if the old token needs to be revoked, but does mean that you can't have multiple authentication tokens for the same wallet. Only the last generated token will always be valid.</p> <p>Example</p> <pre><code>curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet/{wallet_id}/token\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"X-Api-Key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d { \"wallet_key\": \"example-encryption-key-02\" }\n</code></pre> <p><code>Response</code></p> <pre><code>{\n  \"token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ3YWxsZXRfaWQiOiIzYjY0YWQwZC1mNTU2LTRjMDQtOTJiYy1jZDk1YmZkZTU4Y2QifQ.A4eWbSR2M1Z6mbjcSLOlciBuUejehLyytCVyeUlxI0E\"\n}\n</code></pre> <p>In unmanaged mode, the get token endpoint also requires the <code>wallet_key</code> parameter to be included in the request body. The wallet key will be included in the JWT so the wallet can be unlocked when making requests to the admin API.</p> <pre><code>{\n  \"wallet_id\": \"wallet_id\",\n  // \"wallet_key\" in only present in unmanaged mode\n  \"wallet_key\": \"wallet_key\"\n}\n</code></pre> <p>In unmanaged mode, sending the <code>wallet_key</code> to unlock the wallet in every request is not \u201csecure\u201d but keeps it simple at the moment. Eventually, the authentication method should be pluggable, and unmanaged mode would just mean that the key to unlock the wallet is not managed by ACA-Py.</p>"},{"location":"features/Multitenancy/#jwt-secret","title":"JWT Secret","text":"<p>For deterministic JWT creation and verification between restarts and multiple instances, the same JWT secret would need to be used. Therefore a <code>--jwt-secret</code> param is added to the ACA-Py agent that will be used for JWT creation and verification.</p>"},{"location":"features/Multitenancy/#swaggerui","title":"SwaggerUI","text":"<p>When using the SwaggerUI you can click the  icon next to each of the endpoints or the <code>Authorize</code> button at the top to set the correct authentication headers. Make sure to also include the <code>Bearer</code> part in the input field. This won't be automatically added.</p> <p></p>"},{"location":"features/Multitenancy/#tenant-management","title":"Tenant Management","text":"<p>After registering a tenant which effectively creates a subwallet, you may need to update the tenant information or delete it.  The following describes how to accomplish both goals.</p>"},{"location":"features/Multitenancy/#update-a-tenant","title":"Update a tenant","text":"<p>The following properties can be updated: <code>image_url</code>, <code>label</code>, <code>wallet_dispatch_type</code>, and <code>wallet_webhook_urls</code> for tenants of a multitenancy wallet.  To update these properties you will <code>PUT</code> a request json containing the properties you wish to update along with the updated values to the <code>/multitenancy/wallet/${TENANT_WALLET_ID}</code> admin endpoint.  If the Admin API endpoint is protected, you will also include the Admin API Key in the request header.</p> <p>Example</p> <pre><code>update_tenant='{\n  \"image_url\": \"https://aries.ca/images/sample-updated.png\",\n  \"label\": \"example-label-02-updated\",\n  \"wallet_webhook_urls\": [\n    \"https://example.com/webhook/updated\"\n  ]\n}'\n</code></pre> <pre><code>echo $update_tenant | curl  -X PUT \"${ACAPY_ADMIN_URL}/multitenancy/wallet/${TENANT_WALLET_ID}\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"x-api-key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d @-\n</code></pre> <p><code>Response</code></p> <pre><code>{\n  \"settings\": {\n    \"wallet.type\": \"askar\",\n    \"wallet.name\": \"example-name-02\",\n    \"wallet.webhook_urls\": [\n      \"https://example.com/webhook/updated\"\n    ],\n    \"wallet.dispatch_type\": \"default\",\n    \"default_label\": \"example-label-02-updated\",\n    \"image_url\": \"https://aries.ca/images/sample-updated.png\",\n    \"wallet.id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\"\n  },\n  \"key_management_mode\": \"managed\",\n  \"updated_at\": \"2022-04-01T16:23:58.642004Z\",\n  \"wallet_id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\",\n  \"created_at\": \"2022-04-01T15:12:35.474975Z\"\n}\n</code></pre> <p>An Admin API Key is all that is ALLOWED to be included in a request header during an update.  Including the Bearer token header will result in a 404: Unauthorized error</p>"},{"location":"features/Multitenancy/#remove-a-tenant","title":"Remove a tenant","text":"<p>The following information is required to delete a tenant:</p> <ul> <li>wallet_id</li> <li>wallet_key</li> <li>{Admin_Api_Key} if admin is protected</li> </ul> <p>Example</p> <pre><code>curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet/{wallet_id}/remove\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"x-api-key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d '{ \"wallet_key\": \"example-encryption-key-02\" }'\n</code></pre> <p><code>Response</code></p> <pre><code>{}\n</code></pre>"},{"location":"features/Multitenancy/#per-tenant-settings","title":"Per tenant settings","text":"<p>To allow the configuring of ACA-Py startup parameters/environment variables at a tenant/subwallet level. PR#2233 will provide the ability to update the following subset of settings when creating or updating the subwallet:</p> Labels Setting ACAPY_LOG_LEVEL log-level log.level ACAPY_INVITE_PUBLIC invite-public debug.invite_public ACAPY_PUBLIC_INVITES public-invites public_invites ACAPY_AUTO_ACCEPT_INVITES auto-accept-invites debug.auto_accept_invites ACAPY_AUTO_ACCEPT_REQUESTS auto-accept-requests debug.auto_accept_requests ACAPY_AUTO_PING_CONNECTION auto-ping-connection auto_ping_connection ACAPY_MONITOR_PING monitor-ping debug.monitor_ping ACAPY_AUTO_RESPOND_MESSAGES auto-respond-messages debug.auto_respond_messages ACAPY_AUTO_RESPOND_CREDENTIAL_OFFER auto-respond-credential-offer debug.auto_respond_credential_offer ACAPY_AUTO_RESPOND_CREDENTIAL_REQUEST auto-respond-credential-request debug.auto_respond_credential_request ACAPY_AUTO_VERIFY_PRESENTATION auto-verify-presentation debug.auto_verify_presentation ACAPY_NOTIFY_REVOCATION notify-revocation revocation.notify ACAPY_AUTO_REQUEST_ENDORSEMENT auto-request-endorsement endorser.auto_request ACAPY_AUTO_WRITE_TRANSACTIONS auto-write-transactions endorser.auto_write ACAPY_CREATE_REVOCATION_TRANSACTIONS auto-create-revocation-transactions endorser.auto_create_rev_reg ACAPY_ENDORSER_ROLE endorser-protocol-role endorser.protocol_role <ul> <li><code>POST /multitenancy/wallet</code></li> </ul> <p>Added <code>extra_settings</code> dict field to request schema. <code>extra_settings</code> can be configured in the request body as below:</p> <p><code>Example Request</code></p> <pre><code>{\n    \"wallet_name\": \" ... \",\n    \"default_label\": \" ... \",\n    \"wallet_type\": \" ... \",\n    \"wallet_key\": \" ... \",\n    \"key_management_mode\": \"managed\",\n    \"wallet_webhook_urls\": [],\n    \"wallet_dispatch_type\": \"base\",\n    \"extra_settings\": {\n        \"ACAPY_LOG_LEVEL\": \"INFO\",\n        \"ACAPY_INVITE_PUBLIC\": true,\n        \"public-invites\": true\n    },\n}\n</code></pre> <pre><code>echo $new_tenant | curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Api-Key: $ACAPY_ADMIN_URL_API_KEY\" \\\n  -d @-\n</code></pre> <ul> <li><code>PUT /multitenancy/wallet/{wallet_id}</code></li> </ul> <p>Added <code>extra_settings</code> dict field to request schema.</p> <p><code>Example Request</code></p> <pre><code>  {\n    \"wallet_webhook_urls\": [ ... ],\n    \"wallet_dispatch_type\": \"default\",\n    \"label\": \" ... \",\n    \"image_url\": \" ... \",\n    \"extra_settings\": {\n        \"ACAPY_LOG_LEVEL\": \"INFO\",\n        \"ACAPY_INVITE_PUBLIC\": true,\n        \"ACAPY_PUBLIC_INVITES\": false\n    },\n  }\n</code></pre> <pre><code>  echo $update_tenant | curl  -X PUT \"${ACAPY_ADMIN_URL}/multitenancy/wallet/${WALLET_ID}\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"x-api-key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d @-\n</code></pre>"},{"location":"features/PlugIns/","title":"Deeper Dive: Aca-Py Plug-Ins","text":""},{"location":"features/PlugIns/#whats-in-a-plug-in-and-how-does-it-work","title":"What's in a Plug-In and How does it Work?","text":"<p>Plug-ins are loaded on Aca-Py startup based on the following parameters:</p> <ul> <li><code>--plugin</code> - identifies the plug-in library to load</li> <li><code>--block-plugin</code> - identifies plug-ins (including built-ins) that are not to be loaded</li> <li><code>--plugin-config</code> - identify a configuration parameter for a plug-in</li> <li><code>--plugin-config-value</code> - identify a value for a plug-in configuration</li> </ul> <p>The <code>--plug-in</code> parameter specifies a package that is loaded by Aca-Py at runtime, and extends Aca-Py by adding support for additional protocols and message types, and/or extending the Admin API with additional endpoints.</p> <p>The original plug-in design (which we will call the \"old\" model) explicitly included <code>message_types.py</code> <code>routes.py</code> (to add Admin API's).  But functionality was added later (we'll call this the \"new\" model) to allow the plug-in to include a generic <code>setup</code> package that could perform arbitrary initialization.  The \"new\" model also includes support for a <code>definition.py</code> file that can specify plug-in version information  (major/minor plug-in version, as well as the minimum supported version (if another agent is running an older version of the plug-in)).</p> <p>You can discover which plug-ins are installed in an aca-py instance by calling (in the \"server\" section) the <code>GET /plugins</code> endpoint.  (Note that this will return all loaded protocols, including the built-ins.  You can call the <code>GET /status/config</code> to inspect the Aca-Py configuration, which will include the configuration for the external plug-ins.)</p>"},{"location":"features/PlugIns/#setup-method","title":"setup method","text":"<p>If a setup method is provided, it will be called.  If not, the <code>message_types.py</code> and <code>routes.py</code> will be explicitly loaded.</p> <p>This would be in the <code>package/module __init__.py</code>:</p> <pre><code>async def setup(context: InjectionContext):\n    pass\n</code></pre> <p>TODO I couldn't find an implementation of a custom <code>setup</code> in any of the existing plug-ins, so I'm not completely sure what are the best practices for this option.</p>"},{"location":"features/PlugIns/#message_typespy","title":"message_types.py","text":"<p>When loading a plug-in, if there is a <code>message_types.py</code> available, Aca-Py will check the following attributes to initialize the protocol(s):</p> <ul> <li><code>MESSAGE_TYPES</code> - identifies message types supported by the protocol</li> <li><code>CONTROLLERS</code> - identifies protocol controllers</li> </ul>"},{"location":"features/PlugIns/#routespy","title":"routes.py","text":"<p>If <code>routes.py</code> is available, then Aca-Py will call the following functions to initialize the Admin endpoints:</p> <ul> <li><code>register()</code> - registers routes for the new Admin endpoints</li> <li><code>register_events()</code> - registers an events this package will listen for/respond to</li> </ul>"},{"location":"features/PlugIns/#definitionpy","title":"definition.py","text":"<p>If <code>definition.py</code> is available, Aca-Py will read this package to determine protocol version information.  An example follows (this is an example that specifies two protocol versions):</p> <pre><code>versions = [\n    {\n        \"major_version\": 1,\n        \"minimum_minor_version\": 0,\n        \"current_minor_version\": 0,\n        \"path\": \"v1_0\",\n    },\n    {\n        \"major_version\": 2,\n        \"minimum_minor_version\": 0,\n        \"current_minor_version\": 0,\n        \"path\": \"v2_0\",\n    },\n]\n</code></pre> <p>The attributes are:</p> <ul> <li><code>major_version</code> - specifies the protocol major version</li> <li><code>current_minor_version</code> - specifies the protocol minor version</li> <li><code>minimum_minor_version</code> - specifies the minimum supported version (if a lower version is installed in another agent)</li> <li><code>path</code> - specifies the sub-path within the package for this version</li> </ul>"},{"location":"features/PlugIns/#loading-aca-py-plug-ins-at-runtime","title":"Loading Aca-Py Plug-Ins at Runtime","text":"<p>The load sequence for a plug-in (the \"Startup\" class depends on how Aca-Py is running - <code>upgrade</code>, <code>provision</code> or <code>start</code>):</p> <pre><code>sequenceDiagram\n  participant Startup\n  Note right of Startup: Configuration is loaded on startup&lt;br/&gt;from aca-py config params\n    Startup-&gt;&gt;+ArgParse: configure\n    ArgParse-&gt;&gt;settings:  [\"external_plugins\"]\n    ArgParse-&gt;&gt;settings:  [\"blocked_plugins\"]\n\n    Startup-&gt;&gt;+Conductor: setup()\n      Note right of Conductor: Each configured plug-in is validated and loaded\n      Conductor-&gt;&gt;DefaultContext:  build_context()\n      DefaultContext-&gt;&gt;DefaultContext:  load_plugins()\n      DefaultContext-&gt;&gt;+PluginRegistry:  register_package() (for built-in protocols)\n        PluginRegistry-&gt;&gt;PluginRegistry:  register_plugin() (for each sub-package)\n      DefaultContext-&gt;&gt;PluginRegistry:  register_plugin() (for non-protocol built-ins)\n      loop for each external plug-in\n      DefaultContext-&gt;&gt;PluginRegistry:  register_plugin()\n      alt if a setup method is provided\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  has setup\n      else if routes and/or message_types are provided\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  has routes\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  has message_types\n      end\n      opt if definition is provided\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  definition()\n      end\n      end\n      DefaultContext-&gt;&gt;PluginRegistry:  init_context()\n        loop for each external plug-in\n        alt if a setup method is provided\n          PluginRegistry-&gt;&gt;ExternalPlugIn:  setup()\n        else if a setup method is NOT provided\n          PluginRegistry-&gt;&gt;PluginRegistry:  load_protocols()\n          PluginRegistry-&gt;&gt;PluginRegistry:  load_protocol_version()\n          PluginRegistry-&gt;&gt;ProtocolRegistry:  register_message_types()\n          PluginRegistry-&gt;&gt;ProtocolRegistry:  register_controllers()\n        end\n        PluginRegistry-&gt;&gt;PluginRegistry:  register_protocol_events()\n      end\n\n      Conductor-&gt;&gt;Conductor:  load_transports()\n\n      Note right of Conductor: If the admin server is enabled, plug-in routes are added\n      Conductor-&gt;&gt;AdminServer:  create admin server if enabled\n\n    Startup-&gt;&gt;Conductor: start()\n      Conductor-&gt;&gt;Conductor:  start_transports()\n      Conductor-&gt;&gt;AdminServer:  start()\n\n    Note right of Startup: the following represents an&lt;br/&gt;admin server api request\n    Startup-&gt;&gt;AdminServer:  setup_context() (called on each request)\n      AdminServer-&gt;&gt;PluginRegistry:  register_admin_routes()\n      loop for each external plug-in\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  routes.register() (to register endpoints)\n      end</code></pre>"},{"location":"features/PlugIns/#developing-a-new-plug-in","title":"Developing a New Plug-In","text":"<p>When developing a new plug-in:</p> <ul> <li>If you are providing a new protocol or defining message types, you should include a <code>definition.py</code> file.</li> <li>If you are providing a new protocol or defining message types, you should include a <code>message_types.py</code> file.</li> <li>If you are providing additional Admin endpoints, you should include a <code>routes.py</code> file.</li> <li>If you are providing any other functionality, you should provide a <code>setup.py</code> file to initialize the custom functionality.  No guidance is currently available for this option.</li> </ul>"},{"location":"features/PlugIns/#pip-vs-poetry-support","title":"PIP vs Poetry Support","text":"<p>Most Aca-Py plug-ins provide support for installing the plug-in using poetry.  It is recommended to include support in your package for installing using either pip or poetry, to provide maximum support for users of your plug-in.</p>"},{"location":"features/PlugIns/#plug-in-demo","title":"Plug-In Demo","text":"<p>TBD</p>"},{"location":"features/PlugIns/#aca-py-plug-ins","title":"Aca-Py Plug-ins","text":"<p>This list was originally published in this hackmd document.</p> Maintainer Name Features Last Update Link BCGov Redis Events Inbound/Outbound message queue Sep 2022 https://github.com/bcgov/aries-acapy-plugin-redis-events Hyperledger Aries Toolbox UI for ACA-py Aug 2022 https://github.com/hyperledger/aries-toolbox Hyperledger Aries ACApy Plugin Toolbox Protocol Handlers Aug 2022 https://github.com/hyperledger/aries-acapy-plugin-toolbox Indicio Data Transfer Specific Data import Aug 2022 https://github.com/Indicio-tech/aries-acapy-plugin-data-transfer Indicio Question &amp; Answer Non-Aries Protocol Aug 2022 https://github.com/Indicio-tech/acapy-plugin-qa Indicio Acapy-plugin-pickup Fetching Messages from Mediator Aug 2022 https://github.com/Indicio-tech/acapy-plugin-pickup Indicio Machine Readable GF Governance Framework Mar 2022 https://github.com/Indicio-tech/mrgf Indicio Cache Redis Cache for Scalability Jul 2022 https://github.com/Indicio-tech/aries-acapy-cache-redis SICPA Dlab Kafka Events Event Bus Integration Aug 2022 https://github.com/sicpa-dlab/aries-acapy-plugin-kafka-events SICPA Dlab DidComm Resolver Universal Resolver for DIDComm Aug 2022 https://github.com/sicpa-dlab/acapy-resolver-didcomm SICPA Dlab Universal Resolver Multi-ledger Reading Jul 2021 https://github.com/sicpa-dlab/acapy-resolver-universal DDX mydata-did-protocol Oct 2022 https://github.com/decentralised-dataexchange/acapy-mydata-did-protocol BCGov Basic Message Storage Basic message storage (traction) Dec 2022 https://github.com/bcgov/traction/tree/develop/plugins/basicmessage_storage BCGov Multi-tenant Provider Multi-tenant Provider (traction) Dec 2022 https://github.com/bcgov/traction/tree/develop/plugins/multitenant_provider BCGov Traction Innkeeper Innkeeper (traction) Feb 2023 https://github.com/bcgov/traction/tree/develop/plugins/traction_innkeeper"},{"location":"features/PlugIns/#references","title":"References","text":"<p>The following links may be helpful or provide additional context for the current plug-in support.  (These are links to issues or pull requests that were raised during plug-in development.)</p> <p>Configuration params:</p> <ul> <li>https://github.com/hyperledger/aries-cloudagent-python/issues/1121</li> <li>https://hackmd.io/ROUzENdpQ12cz3UB9qk1nA</li> <li>https://github.com/hyperledger/aries-cloudagent-python/pull/1226</li> </ul> <p>Loading plug-ins:</p> <ul> <li>https://github.com/hyperledger/aries-cloudagent-python/pull/1086</li> </ul> <p>Versioning for plug-ins:</p> <ul> <li>https://github.com/hyperledger/aries-cloudagent-python/pull/443</li> </ul>"},{"location":"features/SelectiveDisclosureJWTs/","title":"SD-JWT Implementation in ACA-Py","text":"<p>This document describes the implementation of SD-JWTs in ACA-Py according to the Selective Disclosure for JWTs (SD-JWT) Specification, which defines a mechanism for selective disclosure of individual elements of a JSON object used as the payload of a JSON Web Signature structure.</p> <p>This implementation adds an important privacy-preserving feature to JWTs, since the receiver of an unencrypted JWT can view all claims within. This feature allows the holder to present only a relevant subset of the claims for a given presentation. The issuer includes plaintext claims, called disclosures, outside of the JWT. Each disclosure corresponds to a hidden claim within the JWT. When a holder prepares a presentation, they include along with the JWT only the disclosures corresponding to the claims they wish to reveal. The verifier verifies that the disclosures in fact correspond to claim values within the issuer-signed JWT. The verifier cannot view the claim values not disclosed by the holder.</p> <p>In addition, this implementation includes an optional mechanism for key binding, which is the concept of binding an SD-JWT to a holder's public key and requiring that the holder prove possession of the corresponding private key when presenting the SD-JWT.</p>"},{"location":"features/SelectiveDisclosureJWTs/#issuer-instructions","title":"Issuer Instructions","text":"<p>The issuer determines which claims in an SD-JWT can be selectively disclosable. In this implementation, all claims at all levels of the JSON structure are by default selectively disclosable. If the issuer wishes for certain claims to always be visible, they can indicate which claims should not be selectively disclosable, as described below. Essential verification data such as <code>iss</code>, <code>iat</code>, <code>exp</code>, and <code>cnf</code> are always visible.</p> <p>The issuer creates a list of JSON paths for the claims that will not be selectively disclosable. Here is an example payload:</p> <pre><code>{\n    \"birthdate\": \"1940-01-01\",\n    \"address\": {\n        \"street_address\": \"123 Main St\",\n        \"locality\": \"Anytown\",\n        \"region\": \"Anystate\",\n        \"country\": \"US\",\n    },\n    \"nationalities\": [\"US\", \"DE\", \"SA\"],\n}\n</code></pre> Attribute to access JSON path \"birthdate\" \"birthdate\" The country attribute within the address dictionary \"address.country\" The second item in the nationalities list \"nationalities[1] All items in the nationalities list \"nationalities[0:2]\" <p>The specification defines options for how the issuer can handle nested structures with respect to selective disclosability. As mentioned, all claims at all levels of the JSON structure are by default selectively disclosable.</p>"},{"location":"features/SelectiveDisclosureJWTs/#option-1-flat-sd-jwt","title":"Option 1: Flat SD-JWT","text":"<p>The issuer can decide to treat the <code>address</code> claim in the above example payload as a block that can either be disclosed completely or not at all.</p> <p>The issuer lists out all the claims inside \"address\" in the <code>non_sd_list</code>, but not <code>address</code> itself:</p> <pre><code>non_sd_list = [\n    \"address.street_address\",\n    \"address.locality\",\n    \"address.region\",\n    \"address.country\",\n]\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#option-2-structured-sd-jwt","title":"Option 2: Structured SD-JWT","text":"<p>The issuer may instead decide to make the <code>address</code> claim contents selectively disclosable individually.</p> <p>The issuer lists only \"address\" in the <code>non_sd_list</code>.</p> <pre><code>non_sd_list = [\"address\"]\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#option-3-sd-jwt-with-recursive-disclosures","title":"Option 3: SD-JWT with Recursive Disclosures","text":"<p>The issuer may also decide to make the <code>address</code> claim contents selectively disclosable recursively, i.e., the <code>address</code> claim is made selectively disclosable as well as its sub-claims.</p> <p>The issuer lists neither <code>address</code> nor the subclaims of <code>address</code> in the <code>non_sd_list</code>, leaving all with their default selective disclosability. If all claims can be selectively disclosable, the <code>non_sd_list</code> need not be defined explicitly.</p>"},{"location":"features/SelectiveDisclosureJWTs/#walk-through-of-sd-jwt-implementation","title":"Walk-Through of SD-JWT Implementation","text":""},{"location":"features/SelectiveDisclosureJWTs/#signing-sd-jwts","title":"Signing SD-JWTs","text":""},{"location":"features/SelectiveDisclosureJWTs/#example-input-to-walletsd-jwtsign-endpoint","title":"Example input to <code>/wallet/sd-jwt/sign</code> endpoint","text":"<pre><code>{\n  \"did\": \"WpVJtxKVwGQdRpQP8iwJZy\",\n  \"headers\": {},\n  \"payload\": {\n    \"sub\": \"user_42\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\",\n    \"email\": \"johndoe@example.com\",\n    \"phone_number\": \"+1-202-555-0101\",\n    \"phone_number_verified\": true,\n    \"address\": {\n      \"street_address\": \"123 Main St\",\n      \"locality\": \"Anytown\",\n      \"region\": \"Anystate\",\n      \"country\": \"US\"\n    },\n    \"birthdate\": \"1940-01-01\",\n    \"updated_at\": 1570000000,\n    \"nationalities\": [\"US\", \"DE\", \"SA\"],\n    \"iss\": \"https://example.com/issuer\",\n    \"iat\": 1683000000,\n    \"exp\": 1883000000\n  },\n  \"non_sd_list\": [\n    \"given_name\",\n    \"family_name\",\n    \"nationalities\"\n  ]\n}\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#output","title":"Output","text":"<pre><code>\"eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFZERTQSIsICJraWQiOiAiZGlkOnNvdjpXcFZKdHhLVndHUWRScFFQOGl3Slp5I2tleS0xIn0.eyJfc2QiOiBbIkR0a21ha3NkZGtHRjFKeDBDY0kxdmxRTmZMcGFnQWZ1N3p4VnBGRWJXeXciLCAiSlJLb1E0QXVHaU1INWJIanNmNVV4YmJFeDh2YzFHcUtvX0l3TXE3Nl9xbyIsICJNTTh0TlVLNUstR1lWd0swX01kN0k4MzExTTgwVi13Z0hRYWZvRkoxS09JIiwgIlBaM1VDQmdadVRMMDJkV0pxSVY4elUtSWhnalJNX1NTS3dQdTk3MURmLTQiLCAiX294WGNuSW5Yai1SV3BMVHNISU5YaHFrRVAwODkwUFJjNDBISWE1NElJMCIsICJhdnRLVW5Sdnc1clV0TnZfUnAwUll1dUdkR0RzcnJPYWJfVjR1Y05RRWRvIiwgInByRXZJbzBseTVtNTVsRUpTQUdTVzMxWGdVTElOalo5ZkxiRG81U1pCX0UiXSwgImdpdmVuX25hbWUiOiAiSm9obiIsICJmYW1pbHlfbmFtZSI6ICJEb2UiLCAibmF0aW9uYWxpdGllcyI6IFt7Ii4uLiI6ICJPdU1wcEhpYzEySjYzWTBIY2Ffd1BVeDJCTGdUQVdZQjJpdXpMY3lvcU5JIn0sIHsiLi4uIjogIlIxczlaU3NYeVV0T2QyODdEYy1DTVYyMEdvREF3WUVHV3c4ZkVKd1BNMjAifSwgeyIuLi4iOiAid0lJbjdhQlNDVkFZcUF1Rks3Nmpra3FjVGFvb3YzcUhKbzU5WjdKWHpnUSJ9XSwgImlzcyI6ICJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlciIsICJpYXQiOiAxNjgzMDAwMDAwLCAiZXhwIjogMTg4MzAwMDAwMCwgIl9zZF9hbGciOiAic2hhLTI1NiJ9.cIsuGTIPfpRs_Z49nZcn7L6NUgxQumMGQpu8K6rBtv-YRiFyySUgthQI8KZe1xKyn5Wc8zJnRcWbFki2Vzw6Cw~WyJmWURNM1FQcnZicnZ6YlN4elJsUHFnIiwgIlNBIl0~WyI0UGc2SmZ0UnRXdGFPcDNZX2tscmZRIiwgIkRFIl0~WyJBcDh1VHgxbVhlYUgxeTJRRlVjbWV3IiwgIlVTIl0~WyJ4dkRYMDBmalpmZXJpTmlQb2Q1MXFRIiwgInVwZGF0ZWRfYXQiLCAxNTcwMDAwMDAwXQ~WyJYOTlzM19MaXhCY29yX2hudFJFWmNnIiwgInN1YiIsICJ1c2VyXzQyIl0~WyIxODVTak1hM1k3QlFiWUpabVE3U0NRIiwgInBob25lX251bWJlcl92ZXJpZmllZCIsIHRydWVd~WyJRN1FGaUpvZkhLSWZGV0kxZ0Vaal93IiwgInBob25lX251bWJlciIsICIrMS0yMDItNTU1LTAxMDEiXQ~WyJOeWtVcmJYN1BjVE1ubVRkUWVxZXl3IiwgImVtYWlsIiwgImpvaG5kb2VAZXhhbXBsZS5jb20iXQ~WyJlemJwQ2lnVlhrY205RlluVjNQMGJ3IiwgImJpcnRoZGF0ZSIsICIxOTQwLTAxLTAxIl0~WyJvd3ROX3I5Z040MzZKVnJFRWhQU05BIiwgInN0cmVldF9hZGRyZXNzIiwgIjEyMyBNYWluIFN0Il0~WyJLQXktZ0VaWmRiUnNHV1dNVXg5amZnIiwgInJlZ2lvbiIsICJBbnlzdGF0ZSJd~WyJPNnl0anM2SU9HMHpDQktwa0tzU1pBIiwgImxvY2FsaXR5IiwgIkFueXRvd24iXQ~WyI0Nzg5aG5GSjhFNTRsLW91RjRaN1V3IiwgImNvdW50cnkiLCAiVVMiXQ~WyIyaDR3N0FuaDFOOC15ZlpGc2FGVHRBIiwgImFkZHJlc3MiLCB7Il9zZCI6IFsiTXhKRDV5Vm9QQzFIQnhPRmVRa21TQ1E0dVJrYmNrellza1Z5RzVwMXZ5SSIsICJVYkxmVWlpdDJTOFhlX2pYbS15RHBHZXN0ZDNZOGJZczVGaVJpbVBtMHdvIiwgImhsQzJEYVBwT2t0eHZyeUFlN3U2YnBuM09IZ193Qk5heExiS3lPRDVMdkEiLCAia2NkLVJNaC1PaGFZS1FPZ2JaajhmNUppOXNLb2hyYnlhYzNSdXRqcHNNYyJdfV0~\"\n</code></pre> <p>The <code>sd_jwt_sign()</code> method:</p> <ul> <li>Creates the list of claims that are selectively disclosable</li> <li>Uses the <code>non_sd_list</code> compared against the list of JSON paths for all claims to create the list of JSON paths for selectively disclosable claims</li> <li>Separates list splices if necessary</li> <li>Sorts the <code>sd_list</code> so that the claims deepest in the structure are handled first<ul> <li>Since we will wrap the selectively disclosable claim keys, the JSON paths for nested structures do not work properly when the claim key is wrapped in an object</li> </ul> </li> <li>Uses the JSON paths in the <code>sd_list</code> to find each selectively disclosable claim and wrap it in the <code>SDObj</code> defined by the sd-jwt Python library and removes/replaces the original entry</li> <li>For list items, the element itself is wrapped</li> <li>For other objects, the dictionary key is wrapped</li> <li>With this modified payload, the <code>SDJWTIssuerACAPy.issue()</code> method:</li> <li>Checks if there are selectively disclosable claims at any level in the payload</li> <li>Assembles the SD-JWT payload and creates the disclosures</li> <li>Calls <code>SDJWTIssuerACAPy._create_signed_jws()</code>, which is redefined in order to use the ACA-Py <code>jwt_sign</code> method and which creates the JWT</li> <li>Combines and returns the signed JWT with its disclosures and option key binding JWT, as indicated in the specification</li> </ul>"},{"location":"features/SelectiveDisclosureJWTs/#verifying-sd-jwts","title":"Verifying SD-JWTs","text":""},{"location":"features/SelectiveDisclosureJWTs/#example-input-to-walletsd-jwtverify-endpoint","title":"Example input to <code>/wallet/sd-jwt/verify</code> endpoint","text":"<p>Using the output from the <code>/wallet/sd-jwt/sign</code> example above, we have decided to only reveal two of the selectively disclosable claims (<code>user</code> and <code>updated_at</code>) and achieved this by only including the disclosures for those claims. We have also included a key binding JWT following the disclosures.</p> <pre><code>{\n  \"sd_jwt\": \"eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFZERTQSIsICJraWQiOiAiZGlkOnNvdjpXcFZKdHhLVndHUWRScFFQOGl3Slp5I2tleS0xIn0.eyJfc2QiOiBbIkR0a21ha3NkZGtHRjFKeDBDY0kxdmxRTmZMcGFnQWZ1N3p4VnBGRWJXeXciLCAiSlJLb1E0QXVHaU1INWJIanNmNVV4YmJFeDh2YzFHcUtvX0l3TXE3Nl9xbyIsICJNTTh0TlVLNUstR1lWd0swX01kN0k4MzExTTgwVi13Z0hRYWZvRkoxS09JIiwgIlBaM1VDQmdadVRMMDJkV0pxSVY4elUtSWhnalJNX1NTS3dQdTk3MURmLTQiLCAiX294WGNuSW5Yai1SV3BMVHNISU5YaHFrRVAwODkwUFJjNDBISWE1NElJMCIsICJhdnRLVW5Sdnc1clV0TnZfUnAwUll1dUdkR0RzcnJPYWJfVjR1Y05RRWRvIiwgInByRXZJbzBseTVtNTVsRUpTQUdTVzMxWGdVTElOalo5ZkxiRG81U1pCX0UiXSwgImdpdmVuX25hbWUiOiAiSm9obiIsICJmYW1pbHlfbmFtZSI6ICJEb2UiLCAibmF0aW9uYWxpdGllcyI6IFt7Ii4uLiI6ICJPdU1wcEhpYzEySjYzWTBIY2Ffd1BVeDJCTGdUQVdZQjJpdXpMY3lvcU5JIn0sIHsiLi4uIjogIlIxczlaU3NYeVV0T2QyODdEYy1DTVYyMEdvREF3WUVHV3c4ZkVKd1BNMjAifSwgeyIuLi4iOiAid0lJbjdhQlNDVkFZcUF1Rks3Nmpra3FjVGFvb3YzcUhKbzU5WjdKWHpnUSJ9XSwgImlzcyI6ICJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlciIsICJpYXQiOiAxNjgzMDAwMDAwLCAiZXhwIjogMTg4MzAwMDAwMCwgIl9zZF9hbGciOiAic2hhLTI1NiJ9.cIsuGTIPfpRs_Z49nZcn7L6NUgxQumMGQpu8K6rBtv-YRiFyySUgthQI8KZe1xKyn5Wc8zJnRcWbFki2Vzw6Cw~WyJ4dkRYMDBmalpmZXJpTmlQb2Q1MXFRIiwgInVwZGF0ZWRfYXQiLCAxNTcwMDAwMDAwXQ~WyJYOTlzM19MaXhCY29yX2hudFJFWmNnIiwgInN1YiIsICJ1c2VyXzQyIl0~eyJhbGciOiAiRWREU0EiLCAidHlwIjogImtiK2p3dCIsICJraWQiOiAiZGlkOnNvdjpXcFZKdHhLVndHUWRScFFQOGl3Slp5I2tleS0xIn0.eyJub25jZSI6ICIxMjM0NTY3ODkwIiwgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuY29tL3ZlcmlmaWVyIiwgImlhdCI6IDE2ODgxNjA0ODN9.i55VeR7bNt7T8HWJcfj6jSLH3Q7vFk8N0t7Tb5FZHKmiHyLrg0IPAuK5uKr3_4SkjuGt1_iNl8Wr3atWBtXMDA\"\n}\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#verify-output","title":"Verify Output","text":"<p>Note that attributes in the <code>non_sd_list</code> (<code>given_name</code>, <code>family_name</code>, and <code>nationalities</code>), as well as essential verification data (<code>iss</code>, <code>iat</code>, <code>exp</code>) are visible directly within the payload. The disclosures include only the values for the <code>user</code> and <code>updated_at</code> claims, since those are the only selectively disclosable claims that the holder presented. The corresponding hashes for those disclosures appear in the <code>payload[\"_sd\"]</code> list.</p> <pre><code>{\n  \"headers\": {\n    \"typ\": \"JWT\",\n    \"alg\": \"EdDSA\",\n    \"kid\": \"did:sov:WpVJtxKVwGQdRpQP8iwJZy#key-1\"\n  },\n  \"payload\": {\n    \"_sd\": [\n      \"DtkmaksddkGF1Jx0CcI1vlQNfLpagAfu7zxVpFEbWyw\",\n      \"JRKoQ4AuGiMH5bHjsf5UxbbEx8vc1GqKo_IwMq76_qo\",\n      \"MM8tNUK5K-GYVwK0_Md7I8311M80V-wgHQafoFJ1KOI\",\n      \"PZ3UCBgZuTL02dWJqIV8zU-IhgjRM_SSKwPu971Df-4\",\n      \"_oxXcnInXj-RWpLTsHINXhqkEP0890PRc40HIa54II0\",\n      \"avtKUnRvw5rUtNv_Rp0RYuuGdGDsrrOab_V4ucNQEdo\",\n      \"prEvIo0ly5m55lEJSAGSW31XgULINjZ9fLbDo5SZB_E\"\n    ],\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\",\n    \"nationalities\": [\n      {\n        \"...\": \"OuMppHic12J63Y0Hca_wPUx2BLgTAWYB2iuzLcyoqNI\"\n      },\n      {\n        \"...\": \"R1s9ZSsXyUtOd287Dc-CMV20GoDAwYEGWw8fEJwPM20\"\n      },\n      {\n        \"...\": \"wIIn7aBSCVAYqAuFK76jkkqcTaoov3qHJo59Z7JXzgQ\"\n      }\n    ],\n    \"iss\": \"https://example.com/issuer\",\n    \"iat\": 1683000000,\n    \"exp\": 1883000000,\n    \"_sd_alg\": \"sha-256\"\n  },\n  \"valid\": true,\n  \"kid\": \"did:sov:WpVJtxKVwGQdRpQP8iwJZy#key-1\",\n  \"disclosures\": [\n    [\n      \"xvDX00fjZferiNiPod51qQ\",\n      \"updated_at\",\n      1570000000\n    ],\n    [\n      \"X99s3_LixBcor_hntREZcg\",\n      \"sub\",\n      \"user_42\"\n    ]\n  ]\n}\n</code></pre> <p>The <code>sd_jwt_verify()</code> method:</p> <ul> <li>Parses the SD-JWT presentation into its component parts: JWT, disclosures, and optional key binding</li> <li>The JWT payload is parsed from its headers and signature</li> <li>Creates a list of plaintext disclosures</li> <li>Calls <code>SDJWTVerifierACAPy._verify_sd_jwt</code>, which is redefined in order to use the ACA-Py <code>jwt_verify</code> method, and which returns the verified JWT</li> <li>If key binding is used, the key binding JWT is verified and checked against the expected audience and nonce values</li> </ul>"},{"location":"features/SupportedRFCs/","title":"Aries AIP and RFCs Supported in Aries Cloud Agent Python","text":"<p>This document provides a summary of the adherence of ACA-Py to the Aries Interop Profiles, and an overview of the ACA-Py feature set. This document is manually updated and as such, may not be up to date with the most recent release of ACA-Py or the repository <code>main</code> branch. Reminders (and PRs!) to update this page are welcome! If you have any questions, please contact us on the #aries channel on Hyperledger Discord or through an issue in this repo.</p> <p>Last Update: 2024-02-17, Release 0.12.0rc1</p> <p>The checklist version of this document was created as a joint effort between Northern Block, Animo Solutions and the Ontario government, on behalf of the Ontario government.</p>"},{"location":"features/SupportedRFCs/#aip-support-and-interoperability","title":"AIP Support and Interoperability","text":"<p>See the Aries Agent Test Harness and the Aries Interoperability Status for daily interoperability test run results between ACA-Py and other Aries Frameworks and Agents.</p> AIP Version Supported Notes AIP 1.0 Fully supported. AIP 2.0 Fully supported, with a couple of very minor exceptions noted below. <p>A summary of the Aries Interop Profiles and Aries RFCs supported in ACA-Py can be found later in this document.</p>"},{"location":"features/SupportedRFCs/#platform-support","title":"Platform Support","text":"Platform Supported Notes Server Kubernetes BC Gov has extensive experience running ACA-Py on Red Hat's OpenShift Kubernetes Distribution. Docker Official docker images are published to the GitHub  container repository at <code>ghcr.io/hyperledger/aries-cloudagent-python</code>. Desktop Could be run as a local service on the computer iOS Android Browser"},{"location":"features/SupportedRFCs/#agent-types","title":"Agent Types","text":"Role Supported Notes Issuer Holder Verifier Mediator Service See the aries-mediator-service, a pre-configured, production ready Aries Mediator Service based on a released version of ACA-Py. Mediator Client Indy Transaction Author Indy Transaction Endorser Indy Endorser Service See the aries-endorser-service, a pre-configured, production ready Aries Endorser Service based on a released version of ACA-Py."},{"location":"features/SupportedRFCs/#credential-types","title":"Credential Types","text":"Credential Type Supported Notes Hyperledger AnonCreds Includes full issue VC, present proof, and revoke VC support. W3C Verifiable Credentials Data Model Supports JSON-LD Data Integrity Proof Credentials using the <code>Ed25519Signature2018</code>, <code>BbsBlsSignature2020</code> and <code>BbsBlsSignatureProof2020</code> signature suites.Supports the DIF Presentation Exchange data format for presentation requests and presentation submissions.Work currently underway to add support for Hyperledger AnonCreds in W3C VC JSON-LD Format"},{"location":"features/SupportedRFCs/#did-methods","title":"DID Methods","text":"Method Supported Notes \"unqualified\" Pre-DID standard identifiers. Used either in a peer-to-peer context, or as an alternate form of a <code>did:sov</code> DID published on an Indy network. <code>did:sov</code> <code>did:web</code> Resolution only <code>did:key</code> <code>did:peer</code> Algorithms <code>2</code>/<code>3</code> and <code>4</code> Universal Resolver A plug in from SICPA is available that can be added to an ACA-Py installation to support a universal resolver capability, providing support for most DID methods in the W3C DID Method Registry."},{"location":"features/SupportedRFCs/#secure-storage-types","title":"Secure Storage Types","text":"Secure Storage Types Supported Notes Aries Askar Recommended - Aries Askar provides equivalent/evolved secure storage and cryptography support to the \"indy-wallet\" part of the Indy SDK. When using Askar (via the <code>--wallet-type askar</code> startup parameter), other functionality is handled by CredX (AnonCreds) and Indy VDR (Indy ledger interactions). Aries Askar-AnonCreds Recommended - When using Askar/AnonCreds (via the <code>--wallet-type askar-anoncreds</code> startup parameter), other functionality is handled by AnonCreds RS (AnonCreds) and Indy VDR (Indy ledger interactions).This <code>wallet-type</code> will eventually be the same as <code>askar</code> when we have fully integrated the AnonCreds RS library into ACA-Py. Indy SDK  Deprecated Full support for the features of the \"indy-wallet\" secure storage capabilities found in the Indy SDK. <p>New installations of ACA-Py should NOT use the Indy SDK. Existing deployments using the Indy SDK should transition to Aries Askar and related components as soon as possible.</p>"},{"location":"features/SupportedRFCs/#miscellaneous-features","title":"Miscellaneous Features","text":"Feature Supported Notes ACA-Py Plugins The ACA-Py Plugins repository contains a growing set of plugins that are maintained and (mostly) tested against new releases of ACA-Py. Multi use invitations Invitations using public did Implicit pickup of messages in role of mediator Revocable AnonCreds Credentials Multi-Tenancy Documentation Multi-Tenant Management The Traction open source project from BC Gov is a layer on top of ACA-Py that enables the easy management of ACA-Py tenants, with an Administrative UI (\"The Innkeeper\") and a Tenant UI for using ACA-Py in a web UI (setting up, issuing, holding and verifying credentials) Connection-less (non OOB protocol / AIP 1.0) Only for issue credential and present proof Connection-less (OOB protocol / AIP 2.0) Only for present proof Signed Attachments Used for OOB Multi Indy ledger support (with automatic detection) Support added in the 0.7.3 Release. Persistence of mediated messages Plugins in the ACA-Py Plugins repository are available for persistent queue support using Redis and Kafka. Without persistent queue support, messages are stored in an in-memory queue and so are subject to loss in the case of a sudden termination of an ACA-Py process. The in-memory queue is properly handled in the case of a graceful shutdown of an ACA-Py process (e.g. processing of the queue completes and no new messages are accepted). Storage Import &amp; Export Supported by directly interacting with the Aries Askar (e.g., no Admin API endpoint available for wallet import &amp; export). Aries Askar support includes the ability to import storage exported from the Indy SDK's \"indy-wallet\" component. Documentation for migrating from Indy SDK storage to Askar can be found in the Indy SDK to Askar Migration Guide. SD-JWTs Signing and verifying SD-JWTs is supported"},{"location":"features/SupportedRFCs/#supported-rfcs","title":"Supported RFCs","text":""},{"location":"features/SupportedRFCs/#aip-10","title":"AIP 1.0","text":"<p>All RFCs listed in AIP 1.0 are fully supported in ACA-Py. The following table provides notes about the implementation of specific RFCs.</p> RFC Supported Notes 0025-didcomm-transports ACA-Py currently supports HTTP and WebSockets for both inbound and outbound messaging. Transports are pluggable and an agent instance can use multiple inbound and outbound transports. 0160-connection-protocol The agent supports Connection/DID exchange initiated from both plaintext invitations and public DIDs that enable bypassing the invitation message."},{"location":"features/SupportedRFCs/#aip-20","title":"AIP 2.0","text":"<p>All RFCs listed in AIP 2.0 (including the sub-targets) are fully supported in ACA-Py EXCEPT as noted in the table below.</p> RFC Supported Notes 0587-encryption-envelope-v2 Supporting the DIDComm v2 encryption envelope does not make sense until DIDComm v2 is to be supported. 0317-please-ack An investigation was done into supporting <code>please-ack</code> and a number of complications were found. As a result, we expect that <code>please-ack</code> will be dropped from AIP 2.0. It has not been implemented by any Aries frameworks or deployments. <p>There is a PR to the Aries RFCs repository to remove those RFCs from AIP 2.0. If that PR is removed, the RFCs will be removed from the table above.</p>"},{"location":"features/SupportedRFCs/#other-supported-rfcs","title":"Other Supported RFCs","text":"RFC Supported Notes 0031-discover-features Rarely (never?) used, and in implementing the V2 version of the protocol, the V1 version was found to be incomplete and was updated as part of Release 0.7.3 0028-introduce 00509-action-menu"},{"location":"features/UsingOpenAPI/","title":"Aries Cloud Agent-Python (ACA-Py) - OpenAPI Code Generation Considerations","text":"<p>ACA-Py provides an OpenAPI-documented REST interface for administering the agent's internal state and initiating communication with connected agents.</p> <p>The running agent provides a <code>Swagger User Interface</code> that can be browsed and used to test various scenarios manually (see the Admin API Readme for details). However, it is often desirable to produce native language interfaces rather than coding <code>Controllers</code> using HTTP primitives. This is possible using several public code generation (codegen) tools. This page provides some suggestions based on experience with these tools when trying to generate <code>Typescript</code> wrappers. The information should be useful to those trying to generate other languages. Updates to this page based on experience are encouraged.</p>"},{"location":"features/UsingOpenAPI/#aca-py-openapi-raw-output-characteristics","title":"ACA-Py, OpenAPI Raw Output Characteristics","text":"<p>ACA-Py uses aiohttp_apispec tags in code to produce the OpenAPI spec file at runtime dependent on what features have been loaded. How these tags are created is documented in the API Standard Behavior section of the Admin API Readme. The OpenAPI spec is available in raw, unformatted form from a running ACA-Py instance using a route of <code>http://&lt;acapy host and port&gt;/api/docs/swagger.json</code> or from the browser <code>Swagger User Interface</code> directly.</p> <p>The ACA-Py Admin API evolves across releases. To track these changes and ensure conformance with the OpenAPI specification, we provide a tool located at <code>scripts/generate-open-api-spec</code>. This tool starts ACA-Py, retrieves the <code>swagger.json</code> file, and runs codegen tools to generate specifications in both Swagger and OpenAPI formats with <code>json</code> language output. The output of this tool enables comparison with the checked-in <code>open-api/swagger.json</code> and <code>open-api/openapi.json</code>, and also serves as a useful resource for identifying any non-conformance to the OpenAPI specification. At the moment, <code>validation</code> is turned off via the <code>open-api/openAPIJSON.config</code> file, so warning messages are printed for non-conformance, but the <code>json</code> is still output. Most of the warnings reported by <code>generate-open-api-spec</code> relate to missing <code>operationId</code> fields which results in manufactured method names being created by codegen tools. At the moment, aiohttp_apispec does not support adding <code>operationId</code> annotations via tags.</p> <p>The <code>generate-open-api-spec</code> tool was initially created to help identify issues with method parameters not being sorted, resulting in somewhat random ordering each time a codegen operation was performed. This is relevant for languages which do not have support for named parameters such as <code>Javascript</code>. It is recommended that the <code>generate-open-api-spec</code> is run prior to each release, and the resulting <code>open-api/openapi.json</code> file checked in to allow tracking of API changes over time. At the moment, this process is not automated as part of the release pipeline.</p>"},{"location":"features/UsingOpenAPI/#generating-language-wrappers-for-aca-py","title":"Generating Language Wrappers for ACA-Py","text":"<p>There are inevitably differences around <code>best practice</code> for method naming based on coding language and organization standards.</p> <p>Best practice for generating ACA-Py language wrappers is to obtain the raw OpenAPI file from a configured/running ACA-Py instance and then post-process it with a merge utility to match routes and insert desired <code>operationId</code> fields. This allows the greatest flexibility in conforming to external naming requirements.</p> <p>Two major open-source code generation tools are Swagger and OpenAPI Tools. Which of these to use can be very dependent on language support required and preference for the style of code generated.</p> <p>The OpenAPI Tools was found to offer some nice features when generating <code>Typescript</code>. It creates separate files for each class and allows the use of a <code>.openapi-generator-ignore</code> file to override generation if there is a spec file issue that needs to be maintained manually.</p> <p>If generating code for languages that do not support named parameters, it is recommended to specify the <code>useSingleRequestParameter</code> or equivalent in your code generator of choice. The reason is that, as mentioned previously, there have been instances where parameters were not sorted when output into the raw ACA-Py API spec file, and this approach helps remove that risk.</p> <p>Another suggestion for code generation is to keep the <code>modelPropertyNaming</code> set to <code>original</code> when generating code. Although it is tempting to try and enable marshaling into standard naming formats such as <code>camelCase</code>, the reality is that the models represent what is sent on the wire and documented in the Aries Protocol RFCS. It has proven handy to be able to see code references correspond directly with protocol RFCs when debugging. It will also correspond directly with what the <code>model</code> shows when looking at the ACA-Py <code>Swagger UI</code> in a browser if you need to try something out manually before coding. One final point is that on occasions, it has been discovered that the code generation tools don't always get the marshaling correct in all circumstances when changing model name format.</p>"},{"location":"features/UsingOpenAPI/#existing-language-wrappers-for-aca-py","title":"Existing Language Wrappers for ACA-Py","text":""},{"location":"features/UsingOpenAPI/#python","title":"Python","text":"<ul> <li>Aries Cloud Controller Python (GitHub / didx-xyz)</li> <li>Aries Cloud Controller (PyPi)</li> <li>Traction (GitHub / bcgov)</li> <li>acapy-client (GitHub / Indicio-tech)</li> </ul>"},{"location":"features/UsingOpenAPI/#go","title":"Go","text":"<ul> <li>go-acapy-client (GitHub / Idej)</li> </ul>"},{"location":"features/UsingOpenAPI/#java","title":"Java","text":"<ul> <li>ACA-Py Java Client Library (GitHub / hyperledger-labs)</li> </ul>"},{"location":"features/devcontainer/","title":"ACA-Py Development with Dev Container","text":"<p>The following guide will get you up and running and developing/debugging ACA-Py as quickly as possible. We provide a <code>devcontainer</code> and will use <code>VS Code</code> to illustrate.</p> <p>By no means is ACA-Py limited to these tools; they are merely examples.  </p> <p>For information on running demos and tests using provided shell scripts, see DevReadMe readme.</p>"},{"location":"features/devcontainer/#caveats","title":"Caveats","text":"<p>The primary use case for this <code>devcontainer</code> is for developing, debugging and unit testing (pytest) the aries_cloudagent source code.</p> <p>There are limitations running this devcontainer, such as all networking is within this container. This container has docker-in-docker which allows running demos, building docker images, running <code>docker compose</code> all within this container.</p>"},{"location":"features/devcontainer/#files","title":"Files","text":"<p>The <code>.devcontainer</code> folder contains the <code>devcontainer.json</code> file which defines this container. We are using a <code>Dockerfile</code> and <code>post-install.sh</code> to build and configure the container run image. The <code>Dockerfile</code> is simple but in place for simplifying image enhancements (ex. adding <code>poetry</code> to the image). The <code>post-install.sh</code> will install some additional development libraries (including for BDD support).</p>"},{"location":"features/devcontainer/#devcontainer","title":"Devcontainer","text":"<p>What are Development Containers?</p> <p>A Development Container (or Dev Container for short) allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.</p> <p>see https://containers.dev.</p> <p>In this guide, we will use Docker and Visual Studio Code with the Dev Containers Extension installed, please set your machine up with those. As of writing, we used the following:</p> <ul> <li>Docker Version: 20.10.24</li> <li>VS Code Version: 1.79.0</li> <li>Dev Container Extension Version: v0.295.0</li> </ul>"},{"location":"features/devcontainer/#open-aca-py-in-the-devcontainer","title":"Open ACA-Py in the devcontainer","text":"<p>To open ACA-Py in a devcontainer, we open the root of this repository. We can open in 2 ways:</p> <ol> <li>Open Visual Studio Code, and use the Command Palette and use <code>Dev Containers: Open Folder in Container...</code></li> <li>Open Visual Studio Code and <code>File|Open Folder...</code>, you should be prompted to <code>Reopen in Container</code>.</li> </ol> <p>NOTE follow any prompts to install <code>Python Extension</code> or reload window for <code>Pylance</code> when first building the container.</p> <p>ADDITIONAL NOTE we advise that after each time you rebuild the container that you also perform: <code>Developer: Reload Window</code> as some extensions seem to require this in order to work as expected.</p>"},{"location":"features/devcontainer/#devcontainerjson","title":"devcontainer.json","text":"<p>When the .devcontainer/devcontainer.json is opened, you will see it building... it is building a Python 3.9 image (bash shell) and loading it with all the ACA-Py requirements (and black). We also load a few Visual Studio settings (for running Pytests and formatting with Flake and Black).</p>"},{"location":"features/devcontainer/#poetry","title":"Poetry","text":"<p>The Python libraries / dependencies are installed using <code>poetry</code>. For the devcontainer, we DO NOT use virtual environments. This means you will not see or need venv prompts in the terminals and you will not need to run tasks through poetry (ie. <code>poetry run black .</code>). If you need to add new dependencies, you will need to add the dependency via poetry AND you should rebuild your devcontainer.</p> <p>In VS Code, open a Terminal, you should be able to run the following commands:</p> <pre><code>python -m aries_cloudagent -v\ncd aries_cloudagent\nruff check .\nblack . --check\npoetry --version\n</code></pre> <p>The first command should show you that <code>aries_cloudagent</code> module is loaded (ACA-Py). The others are examples of code quality checks that ACA-Py does on commits (if you have <code>precommit</code> installed) and Pull Requests.</p> <p>When running <code>ruff check .</code> in the terminal, you may see <code>error: Failed to initialize cache at /.ruff_cache: Permission denied (os error 13)</code> - that's ok. If there are actual ruff errors, you should see something like:</p> <pre><code>error: Failed to initialize cache at /.ruff_cache: Permission denied (os error 13)\nadmin/base_server.py:7:7: D101 Missing docstring in public class\nFound 1 error.\n</code></pre>"},{"location":"features/devcontainer/#extensions","title":"extensions","text":"<p>We have added Black formatter and Ruff extensions. Although we have added launch settings for both <code>ruff</code> and <code>black</code>, you can also use the extension commands from the command palette.</p> <ul> <li><code>Ruff: Format Document</code></li> <li><code>Ruff: Fix all auto-fixable problems</code></li> </ul> <p>More importantly, these extensions are now added to document save, so files will be formatted and checked. We advise that after each time you rebuild the container that you also perform: <code>Developer: Reload Window</code> to ensure the extensions are loaded correctly.</p>"},{"location":"features/devcontainer/#running-docker-in-docker-demos","title":"Running docker-in-docker demos","text":"<p>Start by running a von-network inside your dev container. Or connect to a hosted ledger. You will need to adjust the ledger configurations if you do this.</p> <pre><code>git clone https://github.com/bcgov/von-network\ncd von-network\n./manage build\n./manage start\ncd ..\n</code></pre> <p>If you want to have revocation then start up a tails server in your dev container. Or connect to a hosted tails server. Once again you will need to adjust the configurations.</p> <pre><code>git clone https://github.com/bcgov/indy-tails-server.git\ncd indy-tails-server/docker\n./manage build\n./manage start\ncd ../..\n</code></pre> <pre><code># open a terminal in VS Code...\ncd demo\n./run_demo faber\n# open a second terminal in VS Code...\ncd demo\n./run_demo alice\n# follow the script...\n</code></pre>"},{"location":"features/devcontainer/#further-reading-and-links","title":"Further Reading and Links","text":"<ul> <li>Development Containers (devcontainers): https://containers.dev</li> <li>Visual Studio Code: https://code.visualstudio.com</li> <li>Dev Containers Extension: marketplace.visualstudio.com</li> <li>Docker: https://www.docker.com</li> <li>Docker Compose: https://docs.docker.com/compose/</li> </ul>"},{"location":"features/devcontainer/#aca-py-debugging","title":"ACA-Py Debugging","text":"<p>To better illustrate debugging pytests and ACA-Py runtime code, let's add some run/debug configurations to VS Code. If you have your own <code>launch.json</code> and <code>settings.json</code>, please cut and paste what you want/need.</p> <pre><code>cp -R .vscode-sample .vscode\n</code></pre> <p>This will add a <code>launch.json</code>, <code>settings.json</code> and multiple ACA-Py configuration files for developing with different scenarios.</p> <ul> <li>Faber: Simple agent to simulate an issuer</li> <li>Alice: Simple agent to simulate a holder</li> <li>Endorser: Simulates the endorser agent in an endorsement required environment</li> <li>Author: Simulates an author agent in a endorsement required environment</li> <li>Multitenant Admin: Includes settings for a multitenant/wallet scenario</li> </ul> <p>Having multiple agents is to demonstrate launching multiple agents in a debug session. Any of the config files and the launch file can be changed and customized to meet your needs. They are all setup to run on different ports so they don't interfere with each other. Running the debug session from inside the dev container allows you to contact other services such as a local ledger or tails server using localhost, while still being able to access the swagger admin api through your browser.</p> <p>For all the agents if you want to use another ledger (von-network) other than localhost you will need to change the <code>genesis-url</code> config. For all the agents if you don't want to support revocation you need to remove or comment out the <code>tails-server-base-url</code> config. If you want to use a non localhost server then you will need to change the url.</p>"},{"location":"features/devcontainer/#faber","title":"Faber","text":"<ul> <li>admin api url = http://localhost:9041</li> <li>study the demo to understand the steps to have the agent in the correct state. Make your public dids and schemas, cred-defs, etc.</li> </ul>"},{"location":"features/devcontainer/#alice","title":"Alice","text":"<ul> <li>admin api url = http://localhost:9011</li> <li>study the demo to get a connection with faber</li> </ul>"},{"location":"features/devcontainer/#endorser","title":"Endorser","text":"<ul> <li>admin api url = http://localhost:9031</li> <li>This config is useful if you want to develop in an environment that requires endorsement. You can run the demo with <code>./run_demo faber --endorser-role author</code> to see all the steps to become and endorser.</li> </ul>"},{"location":"features/devcontainer/#author","title":"Author","text":"<ul> <li>admin api url = http://localhost:9021</li> <li>This config is useful if you want to develop in an environment that requires endorsement. You can run the demo with <code>./run_demo faber --endorser-role author</code> to see all the steps to become and author. You need to uncomment the configurations for automating the connection to endorser.</li> </ul>"},{"location":"features/devcontainer/#multitenant-admin","title":"Multitenant-Admin","text":"<ul> <li>admin api url = http://localhost:9051</li> <li>This is for a multitenant environment where you can create multiple tenants with subwallets with one agent. See Multitenancy</li> </ul>"},{"location":"features/devcontainer/#try-running-faber-and-alice-at-the-same-time-and-add-break-points-and-recreate-the-demo","title":"Try running Faber and Alice at the same time and add break points and recreate the demo","text":"<p>To run your ACA-Py code in debug mode, go to the <code>Run and Debug</code> view, select the agent(s) you want to start and click <code>Start Debugging (F5)</code>.</p> <p>This will start your source code as a running ACA-Py instance, all configuration is in the <code>*.yml</code> files. This is just a sample of a configuration. Note that we are not using a database and are joining to a local VON Network (by default, it would be <code>http://localhost:9000</code>). You could change this or another ledger such as <code>http://test.bcovrin.vonx.io</code>. These are purposefully, very simple configurations.</p> <p>For example, open <code>aries_cloudagent/admin/server.py</code> and set a breakpoint in <code>async def status_handler(self, request: web.BaseRequest):</code>, then call <code>GET /status</code> in the Admin Console and hit your breakpoint.</p>"},{"location":"features/devcontainer/#pytest","title":"Pytest","text":"<p>Pytest is installed and almost ready; however, we must build the test list. In the Command Palette, <code>Test: Refresh Tests</code> will scan and find the tests.</p> <p>See Python Testing for more details, and Test Commands for usage.</p> <p>WARNING: our pytests include coverage, which will prevent the debugger from working. One way around this would be to have a <code>.vscode/settings.json</code> that says not to use coverage (see above). This will allow you to set breakpoints in the pytest and code under test and use commands such as <code>Test: Debug Tests in Current File</code> to start debugging.</p> <p>WARNING: the project configuration found in <code>pyproject.toml</code> include performing <code>ruff</code> checks when we run <code>pytest</code>. Including <code>ruff</code> does not play nice with the Testing view. In order to have our pytests discoverable AND available in the Testing view, we create a <code>.pytest.ini</code> when we build the devcontainer. This file will not be committed to the repo, nor does it impact <code>./scripts/run_tests</code> but it will impact if you manually run the pytest commands locally outside of the devcontainer. Just be aware that the file will stay on your file system after you shutdown the devcontainer.</p>"},{"location":"features/devcontainer/#next-steps","title":"Next Steps","text":"<p>At this point, you now have a development environment where you can add pytests, add ACA-Py code and run and debug it all. Be aware there are limitations with <code>devcontainer</code> and other docker networks. You may need to adjust other docker-compose files not to start their own networks, and you may need to reference containers using <code>host.docker.internal</code>. This isn't a panacea but should get you going in the right direction and provide you with some development tools.</p>"},{"location":"gettingStarted/","title":"Becoming an Indy/Aries Developer","text":"<p>This guide is to get you from (pretty much) zero to developing code for issuing (and verifying) credentials with your own Aries agent. On the way, you'll look at Hyperledger Indy and how it works, find out about the architecture and components of an Aries agent and its underlying messaging protocols. Scan the list of topics below and jump in as soon as you hit a topic you don't know.</p> <p>Note that in the guidance we have here, we include not only the links to look at, but we recommend that you not look at certain material to which you might naturally gravitate. That's because the material is out of date and will take you down some unnecessary rabbit holes. Keep your eyes on the goal - developing with Aries to interact with other agents to (amongst other things) connect, issue, hold, present and verify verifiable credentials.</p> <ul> <li>I've heard of Indy, but I don't know the basics</li> <li>I know about Indy, but what is Aries?</li> <li>Demos - Business Level</li> <li>Aries Agents in Context: The Big Picture</li> <li>Aries Internals - Deployment Components</li> <li>An overview of Aries messaging</li> <li>Demos - Aries Developer</li> <li>Establishing a connection between Aries Agents</li> <li>Issuing an AnonCreds credential: From Issuer to Holder/Prover</li> <li>Presenting an Indy credential: From Holder/Prover to Verifier</li> <li>Next steps: Creating your own Aries Agent</li> <li>What should I work on? Options for Aries/Indy Developers</li> <li>Deeper Dive: DIDComm Messages</li> <li>Deeper Dive: DIDComm Message Routing and Encryption</li> <li>Deeper Dive: Routing Example</li> <li>To Do: Deeper Dive: Running and Connecting to an Indy Network</li> <li>Steps and APIs to support credential revocation with Aries agent</li> <li>Deeper Dive: Aca-Py Plug-Ins</li> </ul> <p>Want to help with this guide? Please add issues or submit a pull request to improve the document. Point out things that are missing, things to improve and especially things that are wrong.</p>"},{"location":"gettingStarted/AgentConnections/","title":"Establishing a connection between Aries Agents","text":"<p>Use an ACA-Py issuer/verifier to establish a connection with an Aries mobile wallet. Run the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/AriesAgentArchitecture/","title":"Aries Cloud Agent Internals: Agent and Controller","text":"<p>This section talks in particular about the architecture of this Aries cloud agent implementation. An instance of an Aries agent is actually made up of to two parts - the agent itself and a controller.</p> <p></p> <p>The agent handles all of the core Aries functionality such as interacting with other agents, managing secure storage, sending event notifications to, and receiving directions from, the controller. The controller provides the business logic that defines how that particular agent instance behaves--how to respond to events in the agent, and when to trigger the agent to initiate events. The controller might be a web or native user interface for a person or it might be coded business rules driven by an enterprise system.</p> <p>Between the two is a simple interface. The agent sends event notifications to the controller and the controller sends administrator messages to the agent. The controller registers a webhook with the agent, and the event notifications are HTTP callbacks, and the agent exposes a REST API to the controller for all of the administrative messages it is configured to handle. Each of the DIDComm protocols supported by the agent adds a set of administrative messages for the controller to use in responding to events. The Aries cloud agent includes an OpenAPI (aka Swagger) user interface for a developer to use to explore the API for a specific agent.</p> <p>As such, the agent is just a configured dependency in an Aries cloud agent deployment. Thus, the vast majority of Aries developers will focus on building controllers (business logic) and perhaps some custom plugins (protocols, as we'll discuss soon) for the agent. Only a relatively small group of Aries cloud agent maintainers will focus on adding and maintaining the agent dependency.</p> <p>Want more details about the agent and controller internals? Take a look at the Aries cloud agent deployment model document.</p> <p>Back to the Aries Developer - Getting Started Guide. </p>"},{"location":"gettingStarted/AriesBasics/","title":"What is Aries?","text":"<p>Hyperledger Aries provides a shared, reusable, interoperable tool kit designed for initiatives and solutions focused on creating, transmitting and storing verifiable digital credentials. It is infrastructure for blockchain-rooted, peer-to-peer interactions. It includes a shared cryptographic wallet for blockchain clients as well as a communications protocol for allowing off-ledger interaction between those clients.  </p> <p>A Hyperledger Aries agent (such as the one in this repository):</p> <ul> <li>enables establishing connections with other DIDComm-based agents (using DIDComm encryption envelopes),</li> <li>exchanges messages between connected agents to execute message protocols (using DIDComm protocols)</li> <li>sends notifications about protocol events to a controller, and</li> <li>exposes an API for responses from the controller with direction in handling protocol events.</li> </ul> <p>The concepts and features that make up the Aries project are documented in the aries-rfcs - but don't dive in there yet! We'll get to the features and concepts to be found there with a guided tour of the key RFCs. The Aries Working Group meets weekly to expand the design and components of Aries.</p> <p>The Aries Cloud Agent Python currently only supports Hyperledger Indy-based verifiable credentials and public ledger. Longer term (as we'll see later in this guide) protocols will be extended or added to support other verifiable credential implementations and public ledgers.</p> <p>Back to the Aries Developer - Getting Started Guide. </p>"},{"location":"gettingStarted/AriesBigPicture/","title":"Aries Agents in context: The Big Picture","text":"<p>Aries agents can be used in a lot of places. This classic Indy Architecture picture shows five agents - the four around the outside (on a phone, a tablet, a laptop and an enterprise server) are referred to as \"edge agents\", and many cloud agents in the blue circle.</p> <p></p> <p>The agents in the picture shares many attributes:</p> <ul> <li>They have some sort of storage for keys and other data related to their role as an agent</li> <li>They interact with other agents using secure. peer-to-peer messaging protocols</li> <li>They have some associated mechanism to provide \"business rules\" to control the behavior of the agent</li> <li>That is often a person for phone, tablet, laptop, etc. based agents</li> <li>That is often backend enterprise systems for enterprise agents</li> <li>Business rules for cloud agents are often about the routing of messages to and from edge agents</li> </ul> <p>While there can be many other agent setups, the picture above shows the most common ones - edge agents for people, edge agents for organizations and cloud agents for routing messages (although cloud agents could be edge agents. Sigh...). A significant emerging use case missing from that picture are agents embedded within/associated with IoT devices. In the common IoT case, IoT device agents are just variants of other edge agents, connected to the rest of the ecosystem through a cloud agent. All the same principles apply.</p> <p>Misleading in the picture is that (almost) all agents connect directly to the Ledger network. In this picture it's the Sovrin ledger, but that could be any Indy network (e.g. set of nodes running indy-node software) and in future, ledgers from other providers. That implies most agents embed the ledger SDK (e.g. indy-sdk) and makes calls to the ledger SDK to interact with the ledger and other SDK controlled resources (e.g. secure storage). Thus, unlike what is implied in the picture, edge agents (commonly) do not call a cloud agent to interact with the ledger - they do it directly. Super small IoT devices are an instance of an exception to that - lacking compute/storage resources and/or connectivity, they might communicate with a cloud agent that would communicate with the ledger.</p> <p>While current Aries agents currently only support Indy-based ledgers, the intention is to add support for other ledgers.</p> <p>The (most common) purpose of cloud agents is to enable secure and privacy preserving routing of messages between edge agents. Rather than messages going directly from edge agent to edge agent (which is often impossible - for example sending to a mobile agent), messages sent from edge agent to edge agent are routed through a sequence of cloud agents. Some of those cloud agents might be controlled by the sender, some by the receiver and others might be gateways owned by agent vendors (called \"Agencies\"). In all cases, an edge agent tells routing agents \"here's how to send messages to me\", so a routing agent sending a message only has to know how to send a peer-to-peer message. While quite complicated, the protocols used by the agents largely take care of this complexity, and most developers don't have to know much about it.</p> <p>Note the many caveats in this section - \"most common\", \"commonly\", etc. There are many small building blocks available in Aries and underlying components that can be combined in infinite ways. We recommend not worrying about the alternate use cases for now. Focus on understanding the common use cases while remembering that other configurations are possible.</p> <p>We also recommend not digging into all the layers described here. Just as you don't have to know how TCP/IP works to write a web app, you don't need to know how indy-node or indy-sdk work to be able to build your first Aries-based application. Later in this guide we'll covering the starting point you do need to know.</p> <p>Back to the Aries Developer - Getting Started Guide.</p>"},{"location":"gettingStarted/AriesDeveloperDemos/","title":"Developer Demos and Samples of Aries Agent","text":"<p>Here are some demos that developers can use to get up to speed on Aries. You don't have to be a developer to use these. If you can use docker and JSON, then that's enough to give these a try.</p>"},{"location":"gettingStarted/AriesDeveloperDemos/#open-api-demo","title":"Open API demo","text":"<p>This demo uses agents (and an Indy ledger), but doesn't implement a controller at all. Instead it uses the OpenAPI (aka Swagger) user interface to let you be the controller to connect agents, issue a credential and then proof that credential.</p> <p>Collaborating Agents OpenAPI Demo</p>"},{"location":"gettingStarted/AriesDeveloperDemos/#python-controller-demo","title":"Python Controller demo","text":"<p>Run this demo to see a couple of simple Python controller implementations for Alice and Faber. Like the previous demo, this shows the agents connecting, Faber issuing a credential to Alice and then requesting a proof based on the credential. Running the demo is simple, but there's a lot for a developer to learn from the code.</p> <p>Python-based Alice/Faber Demo</p>"},{"location":"gettingStarted/AriesDeveloperDemos/#mobile-app-and-web-sample-bc-gov-showcase","title":"Mobile App and Web Sample - BC Gov Showcase","text":"<p>Try out the BC Gov Showcase to download a production Wallet for holding Verifiable Credentials, and then use your new wallet to get and present credentials in some sample scenarios. The end-to-end verifiable credential experience in 30 minutes or less.</p>"},{"location":"gettingStarted/AriesMessaging/","title":"An overview of Aries messaging","text":"<p>Aries Agents communicate with each other via a message mechanism called DIDComm (DID Communication). DIDComm enables secure, asynchronous, end-to-end encrypted messaging between agents, with messages (usually) routed through some configuration of intermediary agents. Aries agents use (an early instance of) the did:peer DID method, which uses DIDs that are not published to a public ledger, but only shared privately between the communicating parties - usually just two agents.</p> <p>Given the underlying secure messaging layer (routing and encryption covered later in the \"Deeper Dive\" sections), DIDComm protocols define standard sets of messages to accomplish a task. For example:</p> <ul> <li>The \"establish connection\" protocol enables two agents to establish a connection through a series of messages - an invitation, a connection request and a connection response.</li> <li>The \"issue credential\" protocol enables an agent to issue a credential to another agent.</li> <li>The \"present proof\" protocol enables an agent to request and receive a proof from another agent.</li> </ul> <p>Each protocol has a specification that defines the protocol's messages, one or more roles for the different participants, and a state machine that defines the state transitions triggered by the messages. For example, in the connection protocol, the messages are \"invitation\", \"connectionRequest\" and \"connectionResponse\", the roles are \"inviter\" and \"invitee\", and the states are \"invited\", \"requested\" and \"connected\". Each participant in an instance of a protocol tracks the state based on the messages they've seen.</p> <p>Code for protocols are implemented as externalized modules from the core agent code so that they can be included (or not) in an agent deployment. The protocol code must include the definition of a state object for the protocol, handlers for the protocol messages, and the events and administrative messages that are available to the controller to inject business logic into the running of the protocol. Each administrative message becomes part of the REST API exposed by the agent instance.</p> <p>Developers building Aries agents for a particular use case will generally focus on building controllers. They must understand the protocols that they are going to need, including the events the controller will receive, and the protocol's administrative messages exposed via the REST API. From time to time, such Aries agent developers might need to implement their own protocols.</p> <p>Back to the Aries Developer - Getting Started Guide. </p>"},{"location":"gettingStarted/AriesRoutingExample/","title":"Aries Routing - an example","text":"<p>In this example, we'll walk through an example of complex routing in Aries, outlining some of the possibilities that can be implemented.</p> <p>We'll start with the Alice and Bob example from the Cross Domain Messaging Aries RFC.</p> <p></p> <p>What are the DIDs involved, what's in their DIDDocs, and what communications are happening between the agents as the connections are made?</p>"},{"location":"gettingStarted/AriesRoutingExample/#the-scenario","title":"The Scenario","text":"<p>Bob and Alice want to establish a connection so that they can communicate. Bob uses an Agency endpoint (<code>https://agents-r-us.ca</code>), labelled as 9 and will have an agent used for routing, labelled as 3. We'll also focus on Bob's messages from his main iPhone, labelled as 4.  We'll ignore Bob's other agents (5 and 6) and we won't worry about Alice's configuration (agents 1, 2 and 8). While the process below is all about Bob, Alice and her agents are doing the same interactions within her domain.</p>"},{"location":"gettingStarted/AriesRoutingExample/#all-the-dids","title":"All the DIDs","text":"<p>A DID and DIDDoc are generated by each participant in each relationship. For Bob's agents (iPhone and Routing), that includes:</p> <ul> <li>Bob and Alice</li> <li>Bob and his Routing Agent</li> <li>Bob and Agency</li> <li>Bob's Routing Agent and Agency</li> </ul> <p>That's a lot more than just the Bob and Alice relationship we usually think about!</p>"},{"location":"gettingStarted/AriesRoutingExample/#diddoc-data","title":"DIDDoc Data","text":"<p>From a routing perspective the important information in the DIDDoc is the following (as defined in the DIDDoc Conventions Aries RFC):</p> <ul> <li>The public keys for agents referenced in the routing</li> <li>The <code>services</code> of type <code>did-communication</code>, including:</li> <li>the one <code>serviceEndpoint</code></li> <li>the <code>recipientKeys</code> array of referenced keys for the ultimate target(s) of the message</li> <li>the <code>routingKeys</code> array of referenced keys for the mediators</li> </ul> <p>Let's look at the <code>did-communication</code> service data in the DIDDocs generated by Bob's iPhone and Routing agents, listed above:</p> <ul> <li>Bob and Alice:</li> <li> <p>The <code>serviceEndpoint</code> that Bob tells Alice about is the endpoint for the Agency.</p> <ul> <li>We'll use for the endpoint the Agency's public DID. That way the Agency can change rotate the keys for the endpoint without all of its clients from having to update every DIDDoc with the new key.</li> </ul> </li> <li> <p>The <code>recipientKeys</code> entry is a key reference for Bob's iPhone specifically for Alice.</p> </li> <li> <p>The <code>routingKeys</code> entries is a reference to the public key for the Routing Agent.</p> </li> <li> <p>Bob and his Routing Agent:</p> </li> <li>The <code>serviceEndpoint</code> is empty because Bob's iPhone has no endpoint. See the note below for more on this.</li> <li>The <code>recipientKeys</code> entry is a key reference for Bob's iPhone specifically for the Routing Agent.</li> <li> <p>The <code>routingKeys</code> array is empty.</p> </li> <li> <p>Bob and Agency:</p> </li> <li>The <code>serviceEndpoint</code> is the endpoint for Bob's Routing Agent.</li> <li>The <code>recipientKeys</code> entry is a key reference for Bob's iPhone specifically for the Agency.</li> <li> <p>The <code>routingKeys</code> is a single entry for the key reference for the Routing Agent key.</p> </li> <li> <p>Bob's Routing Agent and Agency:</p> </li> <li>The <code>serviceEndpoint</code> is the endpoint for Bob's Routing Agent.</li> <li>The <code>recipientKeys</code> entry is a key reference for Bob's Routing Agent specifically for the Agency.</li> <li>The <code>routingKeys</code> array is empty.</li> </ul> <p>The null <code>serviceEndpoint</code> for Bob's iPhone is worth a comment. Mobile apps work by sending requests to servers, but cannot be accessed directly from a server. A DIDComm mechanism (Transports Return Route) enables a server to send messages to a Mobile agent by putting the messages into the response to a request from the mobile agent. While not formalized in an Aries RFC (yet), cloud agents can use mobile platforms' (Apple and Google) notification mechanisms to trigger a user interface event.</p>"},{"location":"gettingStarted/AriesRoutingExample/#preparing-bobs-diddoc-for-alice","title":"Preparing Bob's DIDDoc for Alice","text":"<p>Given that background, let's go through the sequence of events and messages that occur in building a DIDDoc for Bob's edge agent to send to Alice's edge agent. We'll start the sequence with all of the Agents in place as the bootstrapping of the Agency, Routing Agent and Bob's iPhone is trickier than we need to go through here. We'll call that an \"exercise left for the reader\".</p> <p>We'll start the process with Alice sending an out of band connection invitation message to Bob, e.g. through a QR code or a link in an email. Here's one possible sequence for creating the DIDDoc. Note that there are other ways this could be done:</p> <ul> <li>Bob's iPhone agent generates a new DID for Alice and prepares, and partially completes, a DIDDoc</li> <li>Bob messages the Routing Agent to send the newly created DID and to get a new public key for the Alice relationship.</li> <li>The Routing Agent records the DID for Alice and the keypair to be used for messages from Alice.</li> <li>The Routing Agent sends the DID to the Agency to let the Agency know that messages for the new DID are to go to the Routing Agent.</li> <li>The Routing Agent sends the data to Bob's iPhone agent.</li> <li>Bob's iPhone agent fills in the rest of the DIDDoc:</li> <li>the public key for the Routing Agent for the Alice relationship</li> <li>the <code>did-communication</code> service endpoint is set to the Agency public DID and</li> <li>the routing keys array with the values of the Agency public DID key reference and the Routing Agent key reference</li> </ul> <p>Note: Instead of using the DID Bob created, the Agency and Routing Agent might use the public key used to encrypt the messages for their internal routing table look up for where to send a message. In that case, the Bob and the Routing Agent share the public key instead of the DID to their respective upstream routers.</p> <p>With the DIDDoc ready, Bob uses the path provided in the invitation to send a <code>connection-request</code> message to Alice with the new DID and DIDDoc. Alice now knows how to get any DIDComm message to Bob in a secure, end-to-end encrypted manner. Subsequently, when Alice sends messages to Bob's agent, she uses the information in the DIDDoc to securely send the message to the Agency endpoint, it is sent through to the Routing Agent and on to Bob's iPhone agent for processing. Now Bob has the information he needs to securely send any DIDComm message to Alice in a secure, end-to-end encrypted manner.</p> <p>At this time, there are not specific DIDComm protocols for the \"set up the routing\" messages between the agents in Bob's domain (Agency, Routing and iPhone). Those could be implemented to be proprietary by each agent provider (since it's possible one vendor would write the code for each of those agents), but it's likely those will be specified as open standard DIDComm protocols.</p> <p>Based on the DIDDoc that Bob has sent Alice, for her to send a DIDComm message to Bob, Alice must:</p> <ul> <li>Prepare the message for Bob's Agent.</li> <li>Encrypt and place that message into a \"Forward\" message for Bob's Routing Agent.</li> <li>Encrypt and send the \"Forward\" message to Bob's Agency endpoint.</li> </ul>"},{"location":"gettingStarted/ConnectIndyNetwork/","title":"Connecting to an Indy Network","text":"<p>To be completed.</p>"},{"location":"gettingStarted/CredentialRevocation/","title":"Credential Revocation in ACA-Py","text":""},{"location":"gettingStarted/CredentialRevocation/#overview","title":"Overview","text":"<p>Revocation is perhaps the most difficult aspect of verifiable credentials to manage. This is true in AnonCreds, particularly in the management of AnonCreds revocation registries (RevRegs). Through experience in deploying use cases with ACA-Py we have found that it is very difficult for the controller (the application code) to manage revocation registries, and as such, we have changed the implementation in ACA-Py to ensure that it is handling almost all the work in revoking credentials. The only thing the controller writer has to do is track the minimum things necessary to the business rules around revocation, such as whose credentials should be revoked, and how close to real-time should revocations be published?</p> <p>Here is a  summary of all of the AnonCreds revocation activities performed by issuers. After this, we'll provide a (much shorter) list of what an ACA-Py issuer controller has to do. For those interested, there is a more complete overview of AnonCreds revocation, including all of the roles, and some details of the cryptography behind the approach:</p> <ul> <li>Issuers indicate that a credential will support revocation when creating the   credential definition (CredDef).</li> <li>Issuers create a Revocation Registry definition object of a given size   (MaxSize -- the number of credentials that can use the RevReg) and publish it   to the ledger (or more precisely, the verifiable data registry). In doing   that, a Tails file is also created and published somewhere on the Internet,   accessible to all Holders.</li> <li>Issuers create and publish an initial Revocation Registry Entry that defines   the state of all credentials within the RevReg, either all active or all   revoked. It's a really bad idea to create a RevReg starting with \"all   revoked\", so don't do that.</li> <li>Issuers issue credentials and note the \"revocation ID\" of each credential. The   \"revocation Id\" is a compound key consisting of the RevRegId from which the   credential was issued, and the index within that registry of that credential.   An index (from 1 to Max Size of the registry -- or perhaps 0 to Max Size - 1)   can only be associated with one issued credential.</li> <li>At some point, a RevReg is all used up (full), and the Issuer must create another   one. Ideally, this does not cause an extra delay in the process of issuing credentials.</li> <li>At some point, the Issuer revokes the credential of a holder, using the   revocation Id of the relevant credential.</li> <li>At some point, either in conjunction with each revocation, or for a batch of   revocations, the Issuer publishes the RevReg(s) associated with a CredDef to   the ledger. If there are multiple revocations spread across multiple RevRegs,   there may be multiple writes to the ledger.</li> </ul> <p>Since managing RevRegs is really hard for an ACA-Py controller, we have tried to minimize what an ACA-Py Issuer controller has to do, leaving everything else to be handled by ACA-Py. Of the items in the previous list, here is what an ACA-Py issuer controller does:</p> <ul> <li>Issuers flag that revocation will be used when creating the CredDef and the   desired size of the RevReg. ACA-Py takes case of creating the initial   RevReg(s) without further action by the controller.</li> <li>Two RevRegs are initially created, so there is no delay when one fills up,     and another is needed. In ongoing operations, when one RevReg fills up, the     other active RevReg is used, and a new RevReg is created.</li> <li>On creation of each RevReg, its corresponding tails file is published by     ACA-Py.</li> <li>On Issuance, the controller receives the logical \u201crevocation ID\" (combination   of RevRegId+Index) of the issued credential to track.</li> <li>On Revocation, the controller passes in the logical \u201crevocation ID\" of the   credential to be revoked, including a \u201cnotify holder\u201d flag. ACA-Py records the   revocation as pending and, if asked, sends a notification to the holder using   a DIDComm message (Aries RFC 0183: Revocation Notification).</li> <li>The Issuer requests that the revocations for a CredDefId be published. ACA-Py   figures out what RevRegs contain pending revocation and so need to be   published, and publishes each.</li> </ul> <p>That is the minimum amount of tracking the controller must do while still being able to execute the business rules around revoking credentials.</p> <p>From experience, we\u2019ve added to two extra features to deal with unexpected conditions:</p> <ul> <li>When using an Indy (or similar) ledger, if the local copy of a RevReg gets out   of sync with the ledger copy (perhaps due to a failed ledger write), the   Framework can create an update transaction to \u201cfix\u201d the issue. This is needed   for a revocation state using deltas-type solution (like Indy), but not for a   ledger that publishes revocation states containing the entire state of each   credential.</li> <li>From time to time there may be a need to \u201crotate\u201d a   RevReg \u2014 to mark existing, active RevRegs as   \u201cdecommissioned\u201d, and create new ones in their place. We\u2019ve added an endpoint   (api call) for that.</li> </ul>"},{"location":"gettingStarted/CredentialRevocation/#using-aca-py-revocation","title":"Using ACA-Py Revocation","text":"<p>The following are the ACA-Py steps and APIs involved in handling credential revocation.</p> <p>To try these out, use the ACA-Py Alice/Faber demo with tails server support enabled. You will need to have the URL of an running instance of https://github.com/bcgov/indy-tails-server.</p> <p>Include the command line parameter <code>--tails-server-base-url &lt;indy-tails-server url&gt;</code></p> <ol> <li> <p>Publish credential definition</p> <p>Credential definition is created. All required revocation collateral is also created and managed including revocation registry definition, entry, and tails file.</p> <pre><code>POST /credential-definitions\n{\n  \"schema_id\": schema_id,\n  \"support_revocation\": true,\n  # Only needed if support_revocation is true. Defaults to 100\n  \"revocation_registry_size\": size_int,\n  \"tag\": cred_def_tag # Optional\n\n}\nResponse:\n{\n  \"credential_definition_id\": \"credential_definition_id\"\n}\n</code></pre> </li> <li> <p>Issue credential</p> <p>This endpoint manages revocation data. If new revocation registry data is required, it is automatically managed in the background.</p> <pre><code>POST /issue-credential/send-offer\n{\n    \"cred_def_id\": credential_definition_id,\n    \"revoc_reg_id\": revocation_registry_id\n    \"auto_remove\": False, # We need the credential exchange record when revoking\n    ...\n}\nResponse\n{\n    \"credential_exchange_id\": credential_exchange_id\n}\n</code></pre> </li> <li> <p>Revoking credential</p> <pre><code>POST /revocation/revoke\n{\n    \"rev_reg_id\": &lt;revocation_registry_id&gt;\n    \"cred_rev_id\": &lt;credential_revocation_id&gt;,\n    \"publish\": &lt;true|false&gt;\n}\n</code></pre> <p>If publish=false, you must use <code>\u200b/issue-credential\u200b/publish-revocations</code> to publish pending revocations in batches. Revocation are not written to ledger until this is called.</p> </li> <li> <p>When asking for proof, specify the time span when the credential is NOT revoked</p> <pre><code> POST /present-proof/send-request\n {\n   \"connection_id\": ...,\n   \"proof_request\": {\n     \"requested_attributes\": [\n       {\n         \"name\": ...\n         \"restrictions\": ...,\n         ...\n         \"non_revoked\": # Optional, override the global one when specified\n         {\n           \"from\": &lt;seconds from Unix Epoch&gt; # Optional, default is 0\n           \"to\": &lt;seconds from Unix Epoch&gt;\n         }\n       },\n       ...\n     ],\n     \"requested_predicates\": [\n       {\n         \"name\": ...\n         ...\n         \"non_revoked\": # Optional, override the global one when specified\n         {\n           \"from\": &lt;seconds from Unix Epoch&gt; # Optional, default is 0\n           \"to\": &lt;seconds from Unix Epoch&gt;\n         }\n       },\n       ...\n     ],\n     \"non_revoked\": # Optional, only check revocation if specified\n     {\n       \"from\": &lt;seconds from Unix Epoch&gt; # Optional, default is 0\n       \"to\": &lt;seconds from Unix Epoch&gt;\n     }\n   }\n }\n</code></pre> </li> </ol>"},{"location":"gettingStarted/CredentialRevocation/#revocation-notification","title":"Revocation Notification","text":"<p>ACA-Py supports Revocation Notification v1.0.</p> <p>Note: The optional <code>~please_ack</code> is not currently supported.</p>"},{"location":"gettingStarted/CredentialRevocation/#issuer-role","title":"Issuer Role","text":"<p>To notify connections to which credentials have been issued, during step 2 above, include the following attributes in the request body:</p> <ul> <li><code>notify</code> - A boolean value indicating whether or not a notification should be   sent. If the argument <code>--notify-revocation</code> is used on startup, this value   defaults to <code>true</code>. Otherwise, it will default to <code>false</code>. This value   overrides the <code>--notify-revocation</code> flag; the value of <code>notify</code> always takes   precedence.</li> <li><code>connection_id</code> - Connection ID for the connection of the credential holder.   This is required when <code>notify</code> is <code>true</code>.</li> <li><code>thread_id</code> - Message Thread ID of the credential exchange message that   resulted in the credential now being revoked. This is required when <code>notify</code>   is <code>true</code></li> <li><code>comment</code> - An optional comment presented to the credential holder as part of   the revocation notification. This field might contain the reason for   revocation or some other human readable information about the revocation.</li> </ul> <p>Your request might look something like:</p> <pre><code>POST /revocation/revoke\n{\n    \"rev_reg_id\": &lt;revocation_registry_id&gt;\n    \"cred_rev_id\": &lt;credential_revocation_id&gt;,\n    \"publish\": &lt;true|false&gt;,\n    \"notify\": true,\n    \"connection_id\": &lt;connection id&gt;,\n    \"thread_id\": &lt;thread id&gt;,\n    \"comment\": \"optional comment\"\n}\n</code></pre>"},{"location":"gettingStarted/CredentialRevocation/#holder-role","title":"Holder Role","text":"<p>On receipt of a revocation notification, an event with topic <code>acapy::revocation-notification::received</code> and payload containing the thread ID and comment is emitted on the event bus. This can be handled in plugins to further customize notification handling.</p> <p>If the argument <code>--monitor-revocation-notification</code> is used on startup, a webhook with the topic <code>revocation-notification</code> and a payload containing the thread ID and comment is emitted to registered webhook urls.</p>"},{"location":"gettingStarted/CredentialRevocation/#manually-creating-revocation-registries","title":"Manually Creating Revocation Registries","text":"<p>NOTE: This capability is deprecated and will likely be removed entirely in an upcoming release of ACA-Py.</p> <p>The process for creating revocation registries is completely automated - when you create a Credential Definition with revocation enabled, a revocation registry is automatically created (in fact 2 registries are created), and when a registry fills up, a new one is automatically created.</p> <p>However the ACA-Py admin api supports endpoints to explicitly create a new revocation registry, if you desire.</p> <p>There are several endpoints that must be called, and they must be called in this order:</p> <ol> <li> <p>Create revoc registry <code>POST /revocation/create-registry</code></p> </li> <li> <p>you need to provide the credential definition id and the size of the registry</p> </li> <li> <p>Fix the tails file URI <code>PATCH /revocation/registry/{rev_reg_id}</code></p> </li> <li> <p>here you need to provide the full URI that will be written to the ledger, for example:</p> </li> </ol> <pre><code>{\n  \"tails_public_uri\": \"http://host.docker.internal:6543/VDKEEMMSRTEqK4m7iiq5ZL:4:VDKEEMMSRTEqK4m7iiq5ZL:3:CL:8:faber.agent.degree_schema:CL_ACCUM:3cb5c439-928c-483c-a9a8-629c307e6b2d\"\n}\n</code></pre> <ol> <li> <p>Post the revoc def to the ledger <code>POST /revocation/registry/{rev_reg_id}/definition</code></p> </li> <li> <p>if you are an author (i.e. have a DID with restricted ledger write access) then this transaction may need to go through an endorser</p> </li> <li> <p>Write the tails file <code>PUT /revocation/registry/{rev_reg_id}/tails-file</code></p> </li> <li> <p>the tails server will check that the registry definition is already written to the ledger</p> </li> <li> <p>Post the initial accumulator value to the ledger <code>POST /revocation/registry/{rev_reg_id}/entry</code></p> </li> <li> <p>if you are an author (i.e. have a DID with restricted ledger write access) then this transaction may need to go through an endorser</p> </li> <li>this operation MUST be performed on the the new revoc registry def BEFORE any revocation operations are performed</li> </ol>"},{"location":"gettingStarted/CredentialRevocation/#revocation-registry-rotation","title":"Revocation Registry Rotation","text":"<p>From time to time an Issuer may want to issue credentials from a new Revocation Registry. That can be done by changing the Credential Definition, but that could impact verifiers. Revocation Registries go through a series of state changes: <code>init</code>, <code>generated</code>, <code>posted</code>, <code>active</code>, <code>full</code>, <code>decommissioned</code>. When issuing revocable credentials, the work is done with the <code>active</code> registry record. There are always 2 <code>active</code> registry records: one for tracking revocation until it is full, and the second to act as a \"hot swap\" in case issuance is done when the primary is full and being replaced. This ensures that there is always an <code>active</code> registry. When rotating, all registry records (except records in <code>init</code> state) are <code>decommissioned</code> and a new pair of <code>active</code> registry records are created.</p> <p>Issuers can rotate their Credential Definition Revocation Registry records with a simple call: <code>POST /revocation/active-registry/{cred_def_id}/rotate</code></p> <p>It is advised that Issuers ensure the active registry is ready by calling <code>GET /revocation/active-registry/{cred_def_id}</code> after rotation and before issuance (if possible).</p>"},{"location":"gettingStarted/DIDcommMsgs/","title":"Deeper Dive: DIDComm Messaging","text":"<p>DIDComm peer-to-peer messages are asynchronous messages that one agent sends to another - for example, Faber would send to Alice. In between, there may be other agents and message processing, but at the edges, Faber appears to be messaging directly with Alice using encryption based on the DIDs and DIDDocs that the two shared when establishing a connection. The messages are JSON-LD-friendly messages with a \"type\" that defines the namespace, protocol, protocol version and type of the message, an \"id\" that is GUID for the message, and additional fields as required by the message type. The namespace is currently defined to be a public DID that should be globally resolvable to a protocol specification. Currently, \"core\" messages use a DID that is not yet globally resolvable - Daniel Hardman has the keys associated with the DID.</p> <p>Link: Message Types</p> <p>As protocols are executed, the data associated with the protocol is stored in the (currently named) wallet of the agent. The data primarily consists of the state object for that instance of the protocol, and any artifacts of running the protocol. For example, when establishing a connection, the metadata associated with the connection (DIDs, DID Documents and private keys) is stored in the agent's wallet. Likewise, ledger data is cached in the wallet (DIDs, schema, credential definitions, etc.) and credentials. This is taken care of by the Aries agent and the protocols configured into the agent.</p>"},{"location":"gettingStarted/DIDcommMsgs/#message-decorators","title":"Message Decorators","text":"<p>In addition to protocol specific data elements in messages, messages can include \"decorators\", standardized message elements that define cross-cutting behavior. The most common example is the \"thread\" decorator, which is used to link the messages in a protocol instance. As messages go back and forth between agents to complete an instance of a protocol (e.g. issuing a credential), the thread decorator data elements let the agents know to which protocol instance the message belongs. Other currently defined examples of decorators include attachments, localization, tracing and timing. Decorators are often processed by the core of the agent, but some are processed by the protocol message handlers. For example, the thread decorator processed to retrieve the protocol state object for that instance (thread) of the protocol before control is passed to the protocol message handler.</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/","title":"Decentralized Identity Use Case Demos","text":"<p>The following are some demos that you can go through to see verifiable credentials in action. For each of the demos, we've included some guidance on what you should get out of the demo - and where you should stop exploring the demos. Later on in this guide we have some command line demos built on current generation code for developers wanting to look at what's going on under the hood.</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/#bc-gov-showcase","title":"BC Gov Showcase","text":"<p>Try out the BC Gov Showcase to download a production Wallet for holding Verifiable Credentials, and then use your new wallet to get and present credentials in some sample scenarios. The end-to-end verifiable credential experience in 30 minutes or less.</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/#traction-anoncreds-workshop","title":"Traction AnonCreds Workshop","text":"<p>Now that you have a wallet, how about being an issuer, and experience what is needed on that side of an exchange? To do that, try the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/#more-demos-please","title":"More demos, please","text":"<p>Interested in seeing your demos/use cases added to this list? Submit an issue or a PR and we'll see about including it in this list.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/","title":"What should I work on? Options for Aries/Indy Developers","text":"<p>Now that you know the basics of the Indy/Aries eco-system, what do you want to work on? There are many projects at different levels of the eco-system you could choose to work on, and many ways to contribute to the community.</p> <p>This is an important summary for newcomers, as often the temptation is to start at a level far below where you plan to focus your attention. Too often devs coming into the community start at \"the blockchain\"; at <code>indy-node</code> (the Indy public ledger) or the <code>indy-sdk</code>. That is far below where the majority of developers will work and is not really that helpful if what you really want to do is build decentralized identity applications.</p> <p>In the following, we go through the layers from the top of the stack to the bottom. Our expectation is that the majority of developers will work at the application level, and there will be fewer contributing developers each layer down you go. This is not to dissuade anyone from contributing at the lower levels, but rather to say if you are not going to contribute at the lower levels, you don't need to everything about it. It's much like web development - you don't need to know TCP/IP to build web apps.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#building-decentralized-identity-applications","title":"Building Decentralized Identity Applications","text":"<p>If you just want to build enterprise applications on top of the decentralized identity-related Hyperledger projects, you can start with building cloud-based controller apps using any language you want, and deploying your code with an instance of the code in this repository (aries-cloudagent-python).</p> <p>If you want to build a mobile agent, there are open source options available, including Aries-MobileAgent-Xamarin (aka \"Aries MAX\"), which is built on Aries Framework .NET, and Aries Mobile Agent React Native, which is built on Aries Framework JavaScript.</p> <p>As a developer building applications that use/embed Aries agents, you should join the Aries Working Group's weekly calls and watch the aries-rfcs repo to see what protocols are being added and extended. In some cases, you may need to create your own protocols to be added to this repository, and if you are looking for interoperability, you should specify those protocols in an open way, involving the community.</p> <p>Note that if building apps is what you want to do, you don't need to do a deep dive into the Aries SDK, the Indy SDK or the Indy Node public ledger. You need to know the concepts, but it's not a requirement that know the code base intimately.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#contributing-to-aries-cloudagent-python","title":"Contributing to <code>aries-cloudagent-python</code>","text":"<p>Of course as you build applications using <code>aries-cloudagent-python</code>, you will no doubt find deficiencies in the code and features you want added. Contributions to this repo will always be welcome.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#supporting-additional-ledgers","title":"Supporting Additional Ledgers","text":"<p><code>aries-cloudagent-python</code> currently supports only Hyperledger Indy-based public ledgers and verifiable credentials exchange. A goal of Hyperledger Aries is to be ledger-agnostic, and to support other ledgers. We're experimenting with adding support for other ledgers, and would welcome assistance in doing that.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#other-agent-frameworks","title":"Other Agent Frameworks","text":"<p>Although controllers for an <code>aries-cloudagent-python</code> instance can be written in any language, there is definitely a place for functionality equivalent (and better) to what is in this repo in other languages. Use the example provided by the <code>aries-cloudagent-python</code>, evolve that using a different language, and as you discover better ways to do things, discuss and share those improvements in the broader Aries community so that this and other codebases improve.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#improving-aries-sdk","title":"Improving Aries SDK","text":"<p>This code base and other Aries agent implementations currently embed the <code>indy-sdk</code>. However, much of the code in the <code>indy-sdk</code> is being migrated into a variety of Aries language specific repositories. How this migration is to be done is still being decided, but it makes sense that the agent-type things be moved to Aries repositories. A number of language specific Aries SDK repos have been created and are being populated.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#improving-the-indy-sdk","title":"Improving the Indy SDK","text":"<p>Dropping down a level from Aries and into Indy, the indy-sdk needs to continue to evolve. The code base is robust, of high quality and well thought out, but it needs to continue to add new capabilities and improve existing features. The <code>indy-sdk</code> is implemented in Rust, to produce a C-callable library that can be used by client libraries built in a variety of languages.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#improving-indy-node","title":"Improving Indy Node","text":"<p>If you are interested in getting into the public ledger part of Indy, particularly if you are going to be a Sovrin Steward, you should take a deep look into indy-node. Like the <code>indy-sdk</code>, <code>indy-node</code> is robust, of high quality and is well thought out. As the network grows, use cases change and new cryptographic primitives move into the mainstream, <code>indy-node</code> capabilities will need to evolve. <code>indy-node</code> is coded in Python.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#working-in-cryptography","title":"Working in Cryptography","text":"<p>Finally, at the deepest level, and core to all of the projects is the cryptography in Hyperledger Ursa. If you are a cryptographer, that's where you want to be - and we want you there.</p>"},{"location":"gettingStarted/IndyBasics/","title":"Indy, Verifiable Credentials and Decentralized Identity Basics","text":"<p>NOTE: If you are developer building apps on top of Aries and Indy, you DO NOT need to know the nuts and bolts of Indy to build applications. You need to know about verifiable credentials and the concepts of self-sovereign identity. But as an app developer, you don't need to do the Indy getting started pieces. Aries takes care of those details for you. The introduction linked here should be sufficient.</p> <p>If you are new to Indy and verifiable credentials and want to learn the core concepts, this link provides a solid foundation into the goals and purpose of Indy including verifiable credentials, DIDs, decentralized/self-sovereign identity, the Sovrin Foundation and more. The document is the content of the Indy chapter of the Hyperledger edX Blockchain for Business course (which you could also go through).</p> <p>Feel free to do the demo that is referenced in the material, but we recommend that you not dig into that codebase. It's pretty old now - almost a year!  We've got much more relevant examples later in this guide.</p> <p>As well, don't use the guidance in the course to dive into the content about \"Getting Started\" with Indy. Come back here as this content is far more relevant to the current state of Indy and Aries.</p>"},{"location":"gettingStarted/IndyBasics/#tldr","title":"tl;dr","text":"<p>Indy provides an implementation of the basic functions required to implement a network for self-sovereign identity (SSI) - a ledger, client SDKs for interacting with the ledger, DIDs, and capabilities for issuing, holding and proving verifiable credentials.</p> <p>Back to the Aries Developer - Getting Started Guide.</p>"},{"location":"gettingStarted/IssuingAnonCredsCredentials/","title":"Issuing AnonCreds Credentials","text":"<p>Become an issuer, and define, publish and issue verifiable credentials to a mobile wallet. Run the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/PresentingAnonCredsProofs/","title":"Presenting AnonCreds Proofs","text":"<p>Become a verifier, and construct a presentation request, send the request to a mobile wallet, get a presentation derived from AnonCreds verifiable credentials and verify the presentation. Run the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/RoutingEncryption/","title":"Deeper Dive: DIDComm Message Routing and Encryption","text":"<p>Many Aries edge agents do not directly receive messages from a peer edge agent - they have agents in between that route messages to them. This is done for many reasons, such as:</p> <ul> <li>The agent is on a mobile device that does not have a persistent connection and so uses a cloud agent.</li> <li>The person does not want to allow correlation of their agent across relationships and so they use a shared, common endpoint (e.g. <code>https://agents-R-Us.ca</code>) that they are \"hidden in a crowd\".</li> <li>An enterprise wants a single gateway to the many enterprise agents they have in their organization.</li> </ul> <p>Thus, when a DIDComm message is sent from one edge agent to another, it is routed per the instructions of the receiver and for the needs of the sender. For example, in the following picture, Alice might be told by Bob to send messages to his phone (agent 4) via agents 9 and 3, and Alice might always send out messages via agent 2.</p> <p></p> <p>The following looks at how those requirements are met with mediators (for example, agents 9 and 3) and relays (agent 2).</p>"},{"location":"gettingStarted/RoutingEncryption/#inbound-routing-mediators","title":"Inbound Routing - Mediators","text":"<p>To tell a sender how to get a message to it, an agent puts into the DIDDoc for that sender a service endpoint for the recipient (with an encryption key) and an ordered list (possibly empty) of routing keys (called \"mediators\") to use when sending the message. To send the message, the sender must:</p> <ul> <li>Prepare the message to be sent to the recipient</li> <li>Successively encrypt and wrap the message for each intermediate mediator in a \"forward\" message - an envelope.</li> <li>Encrypt and send the message to the first agent in the routing</li> </ul> <p>Note that when an agent uses mediators, it is there responsibility to notify any mediators that need to know of the new relationship that has been formed using the connection protocol and the routing needs of that relationship - where to send messages that arrive destined for a given verkey. Mediator agents have what amounts to a routing table to know when they receive a forward message for a given verkey, where it should go.</p> <p>Link: DIDDoc conventions for inbound routing</p>"},{"location":"gettingStarted/RoutingEncryption/#relays","title":"Relays","text":"<p>Inbound routing described above covers mediators for the receiver that the sender must know about. In addition, either the sender or the receiver may also have relays they use for outbound messages. Relays are routing agents not known to other parties, but that participate in message routing. For example, an enterprise agent might send all outbound traffic to a single gateway in the organization. When sending to a relay, the sender just wraps the message in another \"forward\" message envelope.</p> <p>Link: Mediators and Relays</p>"},{"location":"gettingStarted/RoutingEncryption/#message-encryption","title":"Message Encryption","text":"<p>The DIDComm encryption handling is handling within the Aries agent, and not really something a developer building applications using an agent needs to worry about. Further, within an Aries agent, the handling of the encryption is left to libraries to handle - ultimately calling dependencies from Hyperledger Ursa. To encrypt a message, the agent code calls a <code>pack()</code> function to handle the encryption, and to decrypt a message, the agent code calls a corresponding <code>unpack()</code> function. The \"wire messages\" (as originally called) are described in detail here, including variations for sender authenticated and anonymous encrypting. Wire messages were meant to indicate the handling of a message from one agent directly to another, versus the higher level concept of routing a message from an edge agent to a peer edge agent.</p> <p>Much thought has also gone into repudiable and non-repudiable messaging, as described here.</p>"},{"location":"gettingStarted/YourOwnAriesAgent/","title":"Creating Your Own Aries Agent","text":"<p>Use the \"next steps\" in the Traction AnonCreds Workshop and create your own controller. The Aries ACA-Py Controllers repository has some samples to get you started.</p>"},{"location":"testing/AgentTracing/","title":"Using Tracing in ACA-PY","text":"<p>The aca-py agent supports message tracing, according to the Tracing RFC.</p> <p>Tracing can be enabled globally, for all messages/events, or it can be enabled on an exchange-by-exchange basis.</p> <p>Tracing is configured globally for the agent.</p>"},{"location":"testing/AgentTracing/#aca-py-configuration","title":"ACA-PY Configuration","text":"<p>The following options can be specified when starting the aca-py agent:</p> <pre><code>  --trace               Generate tracing events.\n  --trace-target &lt;trace-target&gt;\n                        Target for trace events (\"log\", \"message\", or http\n                        endpoint).\n  --trace-tag &lt;trace-tag&gt;\n                        Tag to be included when logging events.\n  --trace-label &lt;trace-label&gt;\n                        Label (agent name) used logging events.\n</code></pre> <p>The <code>--trace</code> option enables tracing globally for the agent, the other options can configure the trace destination and content (default is <code>log</code>).</p> <p>Tracing can be enabled on an exchange-by-exchange basis, by including <code>{ ... \"trace\": True, ...}</code> in the JSON payload to the API call (for credential and proof exchanges).</p>"},{"location":"testing/AgentTracing/#enabling-tracing-in-the-alicefaber-demo","title":"Enabling Tracing in the Alice/Faber Demo","text":"<p>The <code>run_demo</code> script supports the following parameters and environment variables.</p> <p>Environment variables:</p> <pre><code>TRACE_ENABLED          Flag to enable tracing\n\nTRACE_TARGET_URL       Host:port of endpoint to log trace events (e.g. logstash:9700)\n\nDOCKER_NET             Docker network to join (must be used if ELK stack is running in docker)\n\nTRACE_TAG              Tag to be included in all logged trace events\n</code></pre> <p>Parameters:</p> <pre><code>--trace-log            Enables tracing to the standard log output\n                       (sets TRACE_ENABLED, TRACE_TARGET, TRACE_TAG)\n\n--trace-http           Enables tracing to an HTTP endpoint (specified by TRACE_TARGET_URL)\n                       (sets TRACE_ENABLED, TRACE_TARGET, TRACE_TAG)\n</code></pre> <p>When running the Faber controller, tracing can be enabled using the <code>T</code> menu option:</p> <pre><code>Faber      | Connected\n    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n[1/2/3/T/X] t\n\n&gt;&gt;&gt; Credential/Proof Exchange Tracing is ON\n    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n\n[1/2/3/T/X] t\n\n&gt;&gt;&gt; Credential/Proof Exchange Tracing is OFF\n    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n\n[1/2/3/T/X]\n</code></pre> <p>When <code>Exchange Tracing</code> is <code>ON</code>, all exchanges will include tracing.</p>"},{"location":"testing/AgentTracing/#logging-trace-events-to-an-elk-stack","title":"Logging Trace Events to an ELK Stack","text":"<p>You can use the <code>ELK</code> stack in the ELK Stack sub-directory as a target for trace events, just start the ELK stack using the docker-compose file and then in two separate bash shells, startup the demo as follows:</p> <pre><code>DOCKER_NET=elknet TRACE_TARGET_URL=logstash:9700 ./run_demo faber --trace-http\n</code></pre> <pre><code>DOCKER_NET=elknet TRACE_TARGET_URL=logstash:9700 ./run_demo alice --trace-http\n</code></pre>"},{"location":"testing/AgentTracing/#hooking-into-event-messaging","title":"Hooking into event messaging","text":"<p>ACA-PY supports sending events to web hooks, which allows the demo agents to display them in the CLI. To also send them to another end point, use the <code>--webhook-url</code> option, which requires the <code>WEBHOOK_URL</code> environment variable. Configure an end point running on the docker host system, port 8888, use the following:</p> <pre><code>WEBHOOK_URL=host.docker.internal:8888 ./run_demo faber --webhook-url\n</code></pre>"},{"location":"testing/INTEGRATION-TESTS/","title":"Integration Tests for Aca-py using Behave","text":"<p>Integration tests for aca-py are implemented using Behave functional tests to drive aca-py agents based on the alice/faber demo framework.</p> <p>If you are new to the ACA-Py integration test suite, this video from ACA-Py Maintainer @ianco describes the Integration Tests in ACA-Py, how to run them and how to add more tests. See also the video at the end of this document about running Aries Agent Test Harness tests before you submit your pull requests.</p>"},{"location":"testing/INTEGRATION-TESTS/#getting-started","title":"Getting Started","text":"<p>To run the aca-py Behave tests, open a bash shell run the following:</p> <pre><code>git clone https://github.com/bcgov/von-network\ncd von-network\n./manage build\n./manage start\ncd ..\ngit clone https://github.com/bcgov/indy-tails-server.git\ncd indy-tails-server/docker\n./manage build\n./manage start\ncd ../..\ngit clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\n./run_bdd -t ~@taa_required\n</code></pre> <p>Note that an Indy ledger and tails server are both required (these can also be specified using environment variables).</p> <p>Note also that some tests require a ledger with TAA enabled, how to run these tests will be described later.</p> <p>By default the test suite runs using a default (SQLite) wallet, to run the tests using postgres run the following:</p> <pre><code># run the above commands, up to cd aries-cloudagent-python/demo\ndocker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres:10\nACAPY_ARG_FILE=postgres-indy-args.yml ./run_bdd\n</code></pre> <p>To run the tests against the back-end <code>askar</code> libraries (as opposed to indy-sdk) run the following:</p> <pre><code>BDD_EXTRA_AGENT_ARGS=\"{\\\"wallet-type\\\":\\\"askar\\\"}\" ./run_bdd -t ~@taa_required\n</code></pre> <p>(Note that <code>wallet-type</code> is currently the only extra argument supported.)</p> <p>You can run individual tests by specifying the tag(s):</p> <pre><code>./run_bdd -t @T001-AIP10-RFC0037\n</code></pre>"},{"location":"testing/INTEGRATION-TESTS/#running-integration-tests-which-require-taa","title":"Running Integration Tests which require TAA","text":"<p>To run a local von-network with TAA enabled,run the following:</p> <pre><code>git clone https://github.com/bcgov/von-network\ncd von-network\n./manage build\n./manage start --taa-sample --logs\n</code></pre> <p>You can then run the TAA-enabled tests as follows:</p> <pre><code>./run_bdd -t @taa_required\n</code></pre> <p>or:</p> <pre><code>BDD_EXTRA_AGENT_ARGS=\"{\\\"wallet-type\\\":\\\"askar\\\"}\" ./run_bdd -t @taa_required\n</code></pre> <p>The agents run on a pre-defined set of ports, however occasionally your local system may already be using one of these ports.  (For example MacOS recently decided to use 8021 for the ftp proxy service.)</p> <p>To overriide the default port settings:</p> <pre><code>AGENT_PORT_OVERRIDE=8030 ./run_bdd -t &lt;some tags&gt;\n</code></pre> <p>(Note that since the test run multiple agents you require up to 60 available ports.)</p>"},{"location":"testing/INTEGRATION-TESTS/#aca-py-integration-tests-vs-aries-agent-test-harness-aath","title":"Aca-py Integration Tests vs Aries Agent Test Harness (AATH)","text":"<p>Aca-py Behave tests are based on the interoperability tests that are implemented in the Aries Agent Test Harness (AATH).  Both use Behave (Gherkin) to execute tests against a running aca-py agent (or in the case of AATH, against any compatible Aries agent), however the aca-py integration tests focus on aca-py specific features.</p> <p>AATH:</p> <ul> <li>Main purpose is to test interoperability between Aries agents</li> <li>Implements detailed tests based on Aries RFC's (runs different scenarios, tests exception paths, etc.)</li> <li>Runs Aries agents using Docker images (agents run for the duration of the tests)</li> <li>Uses a standard \"backchannel\" to support integration of any Aries agent</li> </ul> <p>Aca-py integration tests:</p> <ul> <li>Main purpose is to test aca-py</li> <li>Implements tests based on Aries RFC's, but not to the level of detail as AATH (runs (mostly) happy path scenarios against multiple agent configurations)</li> <li>Tests aca-py specific configurations and features</li> <li>Starts and stops agents for each tests to test different aca-py configurations</li> <li>Uses the same Python framework as used for the interactive Alice/Faber demo</li> </ul>"},{"location":"testing/INTEGRATION-TESTS/#configuration-driven-tests","title":"Configuration-driven Tests","text":"<p>Aca-py integration tests use the same configuration approach as AATH, documented here.</p> <p>In addition to support for external schemas, credential data etc, the aca-py integration tests support configuration of the aca-py agents that are used to run the test.  For example:</p> <pre><code>Scenario Outline: Present Proof where the prover does not propose a presentation of the proof and is acknowledged\n  Given \"3\" agents\n     | name  | role     | capabilities        |\n     | Acme  | issuer   | &lt;Acme_capabilities&gt; |\n     | Faber | verifier | &lt;Acme_capabilities&gt; |\n     | Bob   | prover   | &lt;Bob_capabilities&gt;  |\n  And \"&lt;issuer&gt;\" and \"Bob\" have an existing connection\n  And \"Bob\" has an issued &lt;Schema_name&gt; credential &lt;Credential_data&gt; from &lt;issuer&gt;\n  ...\n\n  Examples:\n     | issuer | Acme_capabilities        | Bob_capabilities | Schema_name    | Credential_data          | Proof_request  |\n     | Acme   | --public-did             |                  | driverslicense | Data_DL_NormalizedValues | DL_age_over_19 |\n     | Faber  | --public-did  --mediator | --mediator       | driverslicense | Data_DL_NormalizedValues | DL_age_over_19 |\n</code></pre> <p>In the above example, the test will run twice using the parameters specified in the \"Examples\" section.  The Acme, Faber and Bob agents will be started for the test and then shut down when the test is completed.</p> <p>The agent's \"capabilities\" are specified using the same command-line parameters that are supported for the Alice/Faber demo agents.</p>"},{"location":"testing/INTEGRATION-TESTS/#global-configuration-for-all-aca-py-agents-under-test","title":"Global Configuration for All Aca-py Agents Under Test","text":"<p>You can specify parameters that are applied to all aca-py agents using the <code>ACAPY_ARG_FILE</code> environment variable, for example:</p> <pre><code>ACAPY_ARG_FILE=postgres-indy-args.yml ./run_bdd\n</code></pre> <p>... will apply the parameters in the <code>postgres-indy-args.yml</code> file (which just happens to configure a postgres wallet) to all agents under test.</p> <p>Or the following:</p> <pre><code>ACAPY_ARG_FILE=askar-indy-args.yml ./run_bdd\n</code></pre> <p>... will run all the tests against an askar wallet (the new shared components, which replace indy-sdk).</p> <p>Any aca-py arguement can be included in the yml file, and order-of-precidence applies (see https://pypi.org/project/ConfigArgParse/).</p>"},{"location":"testing/INTEGRATION-TESTS/#specifying-environment-parameters-when-running-integration-tests","title":"Specifying Environment Parameters when Running Integration Tests","text":"<p>Aca-py integration tests support the following environment-driven configuration:</p> <ul> <li><code>LEDGER_URL</code> - specify the ledger url</li> <li><code>TAILS_NETWORK</code> - specify the docker network the tailer server is running on</li> <li><code>PUBLIC_TAILS_URL</code> - specify the public url of the tails server</li> <li><code>ACAPY_ARG_FILE</code> - specify global aca-py parameters (see above)</li> </ul>"},{"location":"testing/INTEGRATION-TESTS/#running-specific-test-scenarios","title":"Running specific test scenarios","text":"<p>Behave tests are tagged using the same standard tags as used in AATH.</p> <p>To run a specific set of Aca-py integration tests (or exclude specific tests):</p> <pre><code>./run_bdd -t tag1 -t ~tag2\n</code></pre> <p>(All command line parameters are passed to the <code>behave</code> command, so all parameters supported by behave can be used.)</p>"},{"location":"testing/INTEGRATION-TESTS/#aries-agent-test-harness-aca-py-tests","title":"Aries Agent Test Harness ACA-Py Tests","text":"<p>This video is a presentation by Aries Cloud Agent Python (ACA-Py) developer @ianco about using the Aries Agent Test Harness for local pre-release testing of ACA-Py. Have a big change that you want to test with other Aries Frameworks? Following this guidance to run AATH tests with your under-development branch of ACA-Py.</p>"},{"location":"testing/Logging/","title":"Logging docs","text":"<p>ACA_Py supports multiple configurations of logging.</p>"},{"location":"testing/Logging/#log-level","title":"Log level","text":"<p>ACA-Py's logging is based on python's logging lib. Log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARNING</code> are available. Other log levels fall back to <code>WARNING</code>.</p>"},{"location":"testing/Logging/#per-tenant-logging","title":"Per Tenant Logging","text":"<p>Supports writing of log messages to a file with <code>wallet_id</code> as the tenant identifier for each. To enable this, both multitenant mode (<code>--multitenant</code>) and writing to log file option (<code>--log-file</code>) are required. If both <code>--multitenant</code> and <code>--log-file</code> are not passed when starting up ACA-Py, then it will use <code>default_logging_config.ini</code> config (backward compatible) and not log at a per tenant level.</p>"},{"location":"testing/Logging/#command-line-arguments","title":"Command Line Arguments","text":"<ul> <li><code>--log-level</code> - The log level to log on std out</li> <li><code>--log-file</code> - Enables writing of logs to file. The provided value becomes path to a file to log to. If no value or empty string is provided then it will try to get the path from the config file</li> <li><code>--log-config</code> - Specifies a custom logging configuration file</li> </ul> <p>Example:</p> <pre><code>./bin/aca-py start --log-level debug --log-file acapy.log --log-config aries_cloudagent.config:default_per_tenant_logging_config.ini\n\n./bin/aca-py start --log-level debug --log-file --multitenant --log-config ./aries_cloudagent/config/default_per_tenant_logging_config.yml\n</code></pre>"},{"location":"testing/Logging/#environment-variables","title":"Environment Variables","text":"<p>The log level can be configured using the environment variable <code>ACAPY_LOG_LEVEL</code>. The log file can be set by <code>ACAPY_LOG_FILE</code>. The log config can be set by <code>ACAPY_LOG_CONFIG</code>.</p> <p>Example:</p> <pre><code>ACAPY_LOG_LEVEL=info ACAPY_LOG_FILE=./acapy.log ACAPY_LOG_CONFIG=./acapy_log.ini ./bin/aca-py start\n</code></pre>"},{"location":"testing/Logging/#acapy-config-file","title":"Acapy Config File","text":"<p>Following parameters can be used in a configuration file like this.</p> <pre><code>log-level: WARNING\ndebug-connections: false\ndebug-presentations: false\n</code></pre> <p>Warning: debug-connections and debug-presentations must not be used in a production environment as they log also credential claims values. Both parameters are independent of the log level, which means: Also if log-level is set to WARNING, connections and presentations will be logged like in debug log level.</p>"},{"location":"testing/Logging/#log-config-file","title":"Log config file","text":"<p>The path to config file is provided via <code>--log-config</code>.</p> <p>Find an example in default_logging_config.ini.</p> <p>You can find more detail description in the logging documentation.</p> <p>For per tenant logging, find an example in default_per_tenant_logging_config.ini, which sets up  <code>TimedRotatingFileMultiProcessHandler</code> and <code>StreamHandler</code> handlers. Custom <code>TimedRotatingFileMultiProcessHandler</code> handler supports the ability to cleanup logs by time and maintain backup logs and a custom JSON formatter for logs. The arguments for it such as <code>file name</code>, <code>when</code>, <code>interval</code> and <code>backupCount</code> can be passed as <code>args=('acapy.log', 'd', 7, 1,)</code> (also shown below). Note: <code>backupCount</code> of 0 will mean all backup log files will be retained and not deleted at all. More details about these attributes can be found here</p> <pre><code>[loggers]\nkeys=root\n\n[handlers]\nkeys=stream_handler, timed_file_handler\n\n[formatters]\nkeys=formatter\n\n[logger_root]\nlevel=ERROR\nhandlers=stream_handler, timed_file_handler\n\n[handler_stream_handler]\nclass=StreamHandler\nlevel=DEBUG\nformatter=formatter\nargs=(sys.stderr,)\n\n[handler_timed_file_handler]\nclass=logging.handlers.TimedRotatingFileMultiProcessHandler\nlevel=DEBUG\nformatter=formatter\nargs=('acapy.log', 'd', 7, 1,)\n\n[formatter_formatter]\nformat=%(asctime)s %(wallet_id)s %(levelname)s %(pathname)s:%(lineno)d %(message)s\n</code></pre> <p>For <code>DictConfig</code> (<code>dict</code> logging config file), find an example in default_per_tenant_logging_config.yml with same attributes as <code>default_per_tenant_logging_config.ini</code> file.</p> <pre><code>version: 1\nformatters:\n  default:\n    format: '%(asctime)s %(wallet_id)s %(levelname)s %(pathname)s:%(lineno)d %(message)s'\nhandlers:\n  console:\n    class: logging.StreamHandler\n    level: DEBUG\n    formatter: default\n    stream: ext://sys.stderr\n  rotating_file:\n    class: logging.handlers.TimedRotatingFileMultiProcessHandler\n    level: DEBUG\n    filename: 'acapy.log'\n    when: 'd'\n    interval: 7\n    backupCount: 1\n    formatter: default\nroot:\n  level: INFO\n  handlers:\n    - console\n    - rotating_file\n</code></pre>"},{"location":"testing/Troubleshooting/","title":"Troubleshooting Aries Cloud Agent Python","text":"<p>This document contains some troubleshooting information that contributors to the community think may be helpful. Most of the content here assumes the reader has gotten started with ACA-Py and has arrived here because of an issue that came up in their use of ACA-Py.</p> <p>Contributions (via pull request) to this document are welcome. Topics added here will mostly come from reported issues that contributors think would be helpful to the larger community.</p>"},{"location":"testing/Troubleshooting/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Unable to Connect to Ledger</li> <li>Local ledger running?</li> <li>Any Firewalls</li> <li>Damaged, Unpublishable Revocation Registry</li> </ul>"},{"location":"testing/Troubleshooting/#unable-to-connect-to-ledger","title":"Unable to Connect to Ledger","text":"<p>The most common issue hit by first time users is getting an error on startup \"unable to connect to ledger\". Here are a list of things to check when you see that error.</p>"},{"location":"testing/Troubleshooting/#local-ledger-running","title":"Local ledger running?","text":"<p>Unless you specify via startup parameters or environment variables that you are using a public Hyperledger Indy ledger, ACA-Py assumes that you are running a local ledger -- an instance of von-network. If that is the cause -- have you started your local ledger, and did it startup properly.  Things to check:</p> <ul> <li>Any errors in the startup of von-network?</li> <li>Is the von-network webserver (usually at <code>https:/localhost:9000</code>) accessible? If so, can you click on and see the Genesis File?</li> <li>Do you even need a local ledger? If not, you can use a public sandbox ledger,   such as the BCovrin Test ledger, likely by just prefacing your ACA-Py   command with <code>LEDGER_URL=http://test.bcovrin.vonx.io</code>. For example,   when running the Alice-Faber demo in the demo folder, you can run (for   example), the Faber agent using the command:   <code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber</code></li> </ul>"},{"location":"testing/Troubleshooting/#any-firewalls","title":"Any Firewalls","text":"<p>Do you have any firewalls in play that might be blocking the ports that are used by the ledger, notably 9701-9708? To access a ledger the ACA-Py instance must be able to get to those ports of the ledger, regardless if the ledger is local or remote.</p>"},{"location":"testing/Troubleshooting/#damaged-unpublishable-revocation-registry","title":"Damaged, Unpublishable Revocation Registry","text":"<p>We have discovered that in the ACA-Py AnonCreds implementation, it is possible to get into a state where the publishing of updates to a Revocation Registry (RevReg) is impossible. This can happen where ACA-Py starts to publish an update to the RevReg, but the write transaction to the Hyperledger Indy ledger fails for some reason. When a credential revocation is published, aca-py (via indy-sdk or askar/credx) updates the revocation state in the wallet as well as on the ledger.  The revocation state is dependant on whatever the previous revocation state is/was, so if the ledger and wallet are mis-matched the publish will fail. (Andrew/s PR # 1804 (merged) should mitigate but probably won't completely eliminate this from happening).</p> <p>For example, in case we've seen, the write RevRegEntry transaction failed at the ledger because there was a problem with accepting the TAA (Transaction Author Agreement). Once the error occurred, the RevReg state held by the ACA-Py agent, and the RevReg state on the ledger were different. Even after the ability to write to the ledger was restored, the RevReg could still not be published because of the differences in the RevReg state. Such a situation can now be corrected, as follows:</p> <p>To address this issue, some new endpoints were added to ACA-Py in Release 0.7.4, as follows:</p> <ul> <li>GET <code>/revocation/registry/&lt;id&gt;/issued</code> - counts of the number of issued/revoked   within a registry</li> <li>GET <code>/revocation/registry/&lt;id&gt;/issued/details</code> - details of all credentials   issued/revoked within a registry</li> <li>GET <code>/revocation/registry/&lt;id&gt;/issued/indy_recs</code> - calculated rev_reg_delta from   the ledger</li> <li>This is used to compare ledger revoked vs wallet revoked credentials, which     is essentially the state of the RevReg on the ledger and in ACA-Py. Where     there is a difference, we have an error.</li> <li>PUT <code>/revocation/registry/&lt;id&gt;/fix-revocation-entry-state</code> - publish an update   to the RevReg state on the ledger to bring it into alignment with what is in   the ACA-Py instance.</li> <li>There is a boolean parameter (<code>apply_ledger_update</code>) to control whether the     ledger entry actually gets published so, if you are so inclined, you can     call the endpoint to see what the transaction would be, before you actually     try to do a ledger update.  This will return:<ul> <li><code>rev_reg_delta</code> - same as the \".../indy_recs\" endpoint</li> <li><code>accum_calculated</code> - transaction to write to ledger</li> <li><code>accum_fixed</code> - If <code>apply_ledger_update</code>, the transaction actually written   to the ledger</li> </ul> </li> </ul> <p>Note that there is (currently) a backlog item to prevent the wallet and ledger from getting out of sync (e.g. don't update the ACA-Py RevReg state if the ledger write fails), but even after that change is made, having this ability will be retained for use if needed.</p> <p>We originally ran into this due to the TAA acceptance getting lost when switching to multi-ledger (as described here. Note that this is one reason how this \"out of sync\" scenario can occur, but there may be others.</p> <p>We add an integration test that demonstrates/tests this issue here.</p> <p>To run the scenario either manually or using the integration tests, you can do the following:</p> <ul> <li>Start von-network in TAA mode:</li> <li><code>./manage start --taa-sample --logs</code></li> <li>Start the tails server as usual:</li> <li><code>./manage start --logs</code></li> <li>To run the scenario manually, start faber and let the agent know it needs to TAA-accept before doing any ledger writes:</li> <li><code>./run_demo faber --revocation --taa-accept</code>, and then you can run through all the transactions using the Swagger page.</li> <li>To run the scenario via an integration test, run:</li> <li><code>./run_bdd -t @taa_required</code></li> </ul>"},{"location":"testing/UnitTests/","title":"ACA-Py Unit Tests","text":"<p>The following covers the Unit Testing framework in ACA-Py, how to run the tests, and how to add unit tests.</p> <p>This video is a presentation of the material covered in this document by developer @shaangill025.</p>"},{"location":"testing/UnitTests/#running-unit-tests-in-aca-py","title":"Running unit tests in ACA-Py","text":"<ul> <li><code>./scripts/run_tests</code></li> <li><code>./scripts/run_tests aries_clouadagent/protocols/out_of_band/v1_0/tests</code></li> <li><code>./scripts/run_tests_indy</code> includes Indy specific tests</li> </ul>"},{"location":"testing/UnitTests/#pytest","title":"Pytest","text":"<p>Example: aries_cloudagent/core/tests/test_event_bus.py</p> <pre><code>@pytest.fixture\ndef event_bus():\n    yield EventBus()\n\n\n@pytest.fixture\ndef profile():\n    yield async_mock.MagicMock()\n\n\n@pytest.fixture\ndef event():\n    event = Event(topic=\"anything\", payload=\"payload\")\n    yield event\n\nclass MockProcessor:\n    def __init__(self):\n        self.profile = None\n        self.event = None\n\n    async def __call__(self, profile, event):\n        self.profile = profile\n        self.event = event\n\n\n@pytest.fixture\ndef processor():\n    yield MockProcessor()\n</code></pre> <pre><code>def test_sub_unsub(event_bus: EventBus, processor):\n    \"\"\"Test subscribe and unsubscribe.\"\"\"\n    event_bus.subscribe(re.compile(\".*\"), processor)\n    assert event_bus.topic_patterns_to_subscribers\n    assert event_bus.topic_patterns_to_subscribers[re.compile(\".*\")] == [processor]\n    event_bus.unsubscribe(re.compile(\".*\"), processor)\n    assert not event_bus.topic_patterns_to_subscribers\n</code></pre> <p>From aries_cloudagent/core/event_bus.py</p> <pre><code>class EventBus:\n    def __init__(self):\n        self.topic_patterns_to_subscribers: Dict[Pattern, List[Callable]] = {}\n\ndef subscribe(self, pattern: Pattern, processor: Callable):\n        if pattern not in self.topic_patterns_to_subscribers:\n            self.topic_patterns_to_subscribers[pattern] = []\n        self.topic_patterns_to_subscribers[pattern].append(processor)\n\ndef unsubscribe(self, pattern: Pattern, processor: Callable):\n    if pattern in self.topic_patterns_to_subscribers:\n        try:\n            index = self.topic_patterns_to_subscribers[pattern].index(processor)\n        except ValueError:\n            return\n        del self.topic_patterns_to_subscribers[pattern][index]\n        if not self.topic_patterns_to_subscribers[pattern]:\n            del self.topic_patterns_to_subscribers[pattern]\n</code></pre> <pre><code>@pytest.mark.asyncio\nasync def test_sub_notify(event_bus: EventBus, profile, event, processor):\n    \"\"\"Test subscriber receives event.\"\"\"\n    event_bus.subscribe(re.compile(\".*\"), processor)\n    await event_bus.notify(profile, event)\n    assert processor.profile == profile\n    assert processor.event == event\n</code></pre> <pre><code>async def notify(self, profile: \"Profile\", event: Event):\n    partials = []\n    for pattern, subscribers in self.topic_patterns_to_subscribers.items():\n        match = pattern.match(event.topic)\n\n        if not match:\n            continue\n\n        for subscriber in subscribers:\n            partials.append(\n                partial(\n                    subscriber,\n                    profile,\n                    event.with_metadata(EventMetadata(pattern, match)),\n                )\n            )\n\n    for processor in partials:\n        try:\n            await processor()\n        except Exception:\n            LOGGER.exception(\"Error occurred while processing event\")\n</code></pre>"},{"location":"testing/UnitTests/#asynctest","title":"asynctest","text":"<p>From: aries_cloudagent/protocols/didexchange/v1_0/tests/test.manager.py</p> <pre><code>class TestDidExchangeManager(AsyncTestCase, TestConfig):\n    async def setUp(self):\n        self.responder = MockResponder()\n\n        self.oob_mock = async_mock.MagicMock(\n            clean_finished_oob_record=async_mock.AsyncMock(return_value=None)\n        )\n\n        self.route_manager = async_mock.MagicMock(RouteManager)\n        ...\n        self.profile = InMemoryProfile.test_profile(\n            {\n                \"default_endpoint\": \"http://aries.ca/endpoint\",\n                \"default_label\": \"This guy\",\n                \"additional_endpoints\": [\"http://aries.ca/another-endpoint\"],\n                \"debug.auto_accept_invites\": True,\n                \"debug.auto_accept_requests\": True,\n                \"multitenant.enabled\": True,\n                \"wallet.id\": True,\n            },\n            bind={\n                BaseResponder: self.responder,\n                OobMessageProcessor: self.oob_mock,\n                RouteManager: self.route_manager,\n                ...\n            },\n        )\n        ...\n\n    async def test_receive_invitation_no_auto_accept(self):\n        async with self.profile.session() as session:\n            mediation_record = MediationRecord(\n                role=MediationRecord.ROLE_CLIENT,\n                state=MediationRecord.STATE_GRANTED,\n                connection_id=self.test_mediator_conn_id,\n                routing_keys=self.test_mediator_routing_keys,\n                endpoint=self.test_mediator_endpoint,\n            )\n            await mediation_record.save(session)\n            with async_mock.patch.object(\n                self.multitenant_mgr, \"get_default_mediator\"\n            ) as mock_get_default_mediator:\n                mock_get_default_mediator.return_value = mediation_record\n                invi_rec = await self.oob_manager.create_invitation(\n                    my_endpoint=\"testendpoint\",\n                    hs_protos=[HSProto.RFC23],\n                )\n\n                invitee_record = await self.manager.receive_invitation(\n                    invi_rec.invitation,\n                    auto_accept=False,\n                )\n                assert invitee_record.state == ConnRecord.State.INVITATION.rfc23\n</code></pre> <pre><code>async def receive_invitation(\n    self,\n    invitation: OOBInvitationMessage,\n    their_public_did: Optional[str] = None,\n    auto_accept: Optional[bool] = None,\n    alias: Optional[str] = None,\n    mediation_id: Optional[str] = None,\n) -&gt; ConnRecord:\n    ...\n    accept = (\n        ConnRecord.ACCEPT_AUTO\n        if (\n            auto_accept\n            or (\n                auto_accept is None\n                and self.profile.settings.get(\"debug.auto_accept_invites\")\n            )\n        )\n        else ConnRecord.ACCEPT_MANUAL\n    )\n    service_item = invitation.services[0]\n    # Create connection record\n    conn_rec = ConnRecord(\n        invitation_key=(\n            DIDKey.from_did(service_item.recipient_keys[0]).public_key_b58\n            if isinstance(service_item, OOBService)\n            else None\n        ),\n        invitation_msg_id=invitation._id,\n        their_label=invitation.label,\n        their_role=ConnRecord.Role.RESPONDER.rfc23,\n        state=ConnRecord.State.INVITATION.rfc23,\n        accept=accept,\n        alias=alias,\n        their_public_did=their_public_did,\n        connection_protocol=DIDX_PROTO,\n    )\n\n    async with self.profile.session() as session:\n        await conn_rec.save(\n            session,\n            reason=\"Created new connection record from invitation\",\n            log_params={\n                \"invitation\": invitation,\n                \"their_role\": ConnRecord.Role.RESPONDER.rfc23,\n            },\n        )\n\n        # Save the invitation for later processing\n        ...\n\n    return conn_rec\n</code></pre>"},{"location":"testing/UnitTests/#other-details","title":"Other details","text":"<ul> <li>Error catching</li> </ul> <pre><code>  with self.assertRaises(DIDXManagerError) as ctx:\n     ...\n  assert \" ... error ...\" in str(ctx.exception)\n</code></pre> <ul> <li> <p>function.<code>assert_called_once_with(parameters)</code>   function.<code>assert_called_once()</code></p> </li> <li> <p>pytest.mark setup in <code>setup.cfg</code>   can be attributed at function or class level. Example, <code>@pytest.mark.indy</code></p> </li> <li> <p>Code coverage   </p> </li> </ul>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Hyperledger Aries Cloud Agent - Python","text":"<p>An easy to use Aries agent for building SSI services using any language that supports sending/receiving HTTP requests.</p> <p>Full access to an organized set of all of the ACA-Py documents is available at https://aca-py.org. Check it out! It's much easier to navigate than this GitHub repo for reading the documentation.</p>"},{"location":"#overview","title":"Overview","text":"<p>Hyperledger Aries Cloud Agent Python (ACA-Py) is a foundation for building Verifiable Credential (VC) ecosystems. It operates in the second and third layers of the Trust Over IP framework (PDF) using DIDComm messaging and Hyperledger Aries protocols. The \"cloud\" in the name means that ACA-Py runs on servers (cloud, enterprise, IoT devices, and so forth), and is not designed to run on mobile devices.</p> <p>ACA-Py is built on the Aries concepts and features that make up Aries Interop Profile (AIP) 2.0. ACA-Py\u2019s supported Aries protocols include, most importantly, protocols for issuing, verifying, and holding verifiable credentials using both Hyperledger AnonCreds verifiable credential format, and the W3C Standard Verifiable Credential Data Model format using JSON-LD with LD-Signatures and BBS+ Signatures. Coming soon -- issuing and presenting Hyperledger AnonCreds verifiable credentials using the W3C Standard Verifiable Credential Data Model format.</p> <p>To use ACA-Py you create a business logic controller that \"talks to\" an ACA-Py instance (sending HTTP requests and receiving webhook notifications), and ACA-Py handles the Aries and DIDComm protocols and related functionality. Your controller can be built in any language that supports making and receiving HTTP requests; knowledge of Python is not needed. Together, this means you can focus on building VC solutions using familiar web development technologies, instead of having to learn the nuts and bolts of low-level cryptography and Trust over IP-type Aries protocols.</p> <p>This checklist-style overview document provides a full list of the features in ACA-Py. The following is a list of some of the core features needed for a production deployment, with a link to detailed information about the capability.</p>"},{"location":"#multi-tenant","title":"Multi-Tenant","text":"<p>ACA-Py supports \"multi-tenant\" scenarios. In these scenarios, one (scalable) instance of ACA-Py uses one database instance, and are together capable of managing separate secure storage (for private keys, DIDs, credentials, etc.) for many different actors. This enables (for example) an \"issuer-as-a-service\", where an enterprise may have many VC issuers, each with different identifiers, using the same instance of ACA-Py to interact with VC holders as required. Likewise, an ACA-Py instance could be a \"cloud wallet\" for many holders (e.g. people or organizations) that, for whatever reason, cannot use a mobile device for a wallet. Learn more about multi-tenant deployments here.</p>"},{"location":"#mediator-service","title":"Mediator Service","text":"<p>Startup options allow the use of an ACA-Py as an Aries mediator using core Aries protocols to coordinate its mediation role. Such an ACA-Py instance receives, stores and forwards messages to Aries  agents that (for example) lack an addressable endpoint on the Internet such as a mobile wallet. A live instance of a public mediator based on ACA-Py is available here from Indicio Technologies. Learn more about deploying a mediator here. See the Aries Mediator Service for a \"best practices\" configuration of an Aries mediator.</p>"},{"location":"#indy-transaction-endorsing","title":"Indy Transaction Endorsing","text":"<p>ACA-Py supports a Transaction Endorsement protocol, for agents that don't have write access to an Indy ledger.  Endorser support is documented here.</p>"},{"location":"#scaled-deployments","title":"Scaled Deployments","text":"<p>ACA-Py supports deployments in scaled environments such as in Kubernetes environments where ACA-Py and its storage components can be horizontally scaled as needed to handle the load.</p>"},{"location":"#vc-api-endpoints","title":"VC-API Endpoints","text":"<p>A set of endpoints conforming to the vc-api specification are included to manage w3c credentials and presentations. They are documented here and a postman demo is available here.</p>"},{"location":"#example-uses","title":"Example Uses","text":"<p>The business logic you use with ACA-Py is limited only by your imagination. Possible applications include:</p> <ul> <li>An interface to a legacy system to issue verifiable credentials</li> <li>An authentication service based on the presentation of verifiable credential proofs</li> <li>An enterprise wallet to hold and present verifiable credentials about that enterprise</li> <li>A user interface for a person to use a wallet not stored on a mobile device</li> <li>An application embedded in an IoT device, capable of issuing verifiable credentials about collected data</li> <li>A persistent connection to other agents that enables secure messaging and notifications</li> <li>Custom code to implement a new service.</li> </ul>"},{"location":"#getting-started","title":"Getting Started","text":"<p>For those new to SSI, Aries and ACA-Py, there are a couple of Linux Foundation edX courses that provide a good starting point.</p> <ul> <li>Identity in Hyperledger: Indy, Aries and Ursa</li> <li>Becoming a Hyperledger Aries Developer</li> </ul> <p>The latter is the most useful for developers wanting to get a solid basis in using ACA-Py and other Aries Frameworks.</p> <p>Also included here is a much more concise (but less maintained) Getting Started Guide that will take you from knowing next to nothing about decentralized identity to developing Aries-based business apps and services. You\u2019ll run an Indy ledger (with no ramp-up time), ACA-Py apps and developer-oriented demos. The guide has a table of contents so you can skip the parts you already know.</p>"},{"location":"#understanding-the-architecture","title":"Understanding the Architecture","text":"<p>There is an architectural deep dive webinar presented by the ACA-Py team, and slides from the webinar are also available. The picture below gives a quick overview of the architecture, showing an instance of ACA-Py, a controller and the interfaces between the controller and ACA-Py, and the external paths to other agents and public ledgers on the Internet.</p> <p></p> <p>You can extend ACA-Py using plug-ins, which can be loaded at runtime.  Plug-ins are mentioned in the webinar and are described in more detail here. An ever-expanding set of ACA-Py plugins can be found in the Aries ACA-Py Plugins repository. Check them out -- it might have the very plugin you need!</p>"},{"location":"#installation-and-usage","title":"Installation and Usage","text":"<p>Use the \"install and go\" page for developers if you are comfortable with Trust over IP and Aries concepts. ACA-Py can be run with Docker without installation (highly recommended), or can be installed from PyPi. In the /demo directory there is a full set of demos for developers to use in getting started, and the demo read me is a great starting point for developers to use an \"in-browser\" approach to run a zero-install example. The Read the Docs overview is also a way to understand the internal modules and APIs that make up an ACA-Py instance.</p> <p>If you would like to develop on ACA-Py locally note that we use Poetry for dependency management and packaging, if you are unfamiliar with poetry please see our cheat sheet</p>"},{"location":"#about-the-aca-py-admin-api","title":"About the ACA-Py Admin API","text":"<p>The overview of ACA-Py\u2019s API is a great starting place for learning about the ACA-Py API when you are starting to build your own controller.</p> <p>An ACA-Py instance puts together an OpenAPI-documented REST interface based on the protocols that are loaded. This is used by a controller application (written in any language) to manage the behavior of the agent. The controller can initiate actions (e.g. issuing a credential) and can respond to agent events (e.g. sending a presentation request after a connection is accepted). Agent events are delivered to the controller as webhooks to a configured URL.</p> <p>Technical note: the administrative API exposed by the agent for the controller to use must be protected with an API key (using the --admin-api-key command line arg) or deliberately left unsecured using the --admin-insecure-mode command line arg. The latter should not be used other than in development if the API is not otherwise secured.</p>"},{"location":"#troubleshooting","title":"Troubleshooting","text":"<p>There are a number of resources for getting help with ACA-Py and troubleshooting any problems you might run into. The Troubleshooting document contains some guidance about issues that have been experienced in the past. Feel free to submit PRs to supplement the troubleshooting document! Searching the ACA-Py GitHub issues may uncovers challenges you are having that others have experienced, often with solutions. As well, there is the \"aries-cloudagent-python\" channel on the Hyperledger Discord chat server (invitation here).</p>"},{"location":"#credit","title":"Credit","text":"<p>The initial implementation of ACA-Py was developed by the Government of British Columbia\u2019s Digital Trust Team in Canada. To learn more about what\u2019s happening with decentralized identity and digital trust in British Columbia, checkout the BC Digital Trust website.</p> <p>See the MAINTAINERS.md file for a list of the current ACA-Py maintainers, and the guidelines for becoming a Maintainer. We'd love to have you join the team if you are willing and able to carry out the duties of a Maintainer.</p>"},{"location":"#contributing","title":"Contributing","text":"<p>Pull requests are welcome! Please read our contributions guide and submit your PRs. We enforce developer certificate of origin (DCO) commit signing \u2014\u00a0guidance on this is available. We also welcome issues submitted about problems you encounter in using ACA-Py.</p>"},{"location":"#license","title":"License","text":"<p>Apache License Version 2.0</p>"},{"location":"CHANGELOG/","title":"Aries Cloud Agent Python Changelog","text":""},{"location":"CHANGELOG/#0120rc2","title":"0.12.0rc2","text":""},{"location":"CHANGELOG/#march-5-2024","title":"March 5, 2024","text":"<p>Release 0.12.0 is a relative large release but currently with no breaking changes. We expect there will be breaking changes (at least in the handling of endorsement) before the 0.12.0 release is finalized, hence the minor version update.</p> <p>The <code>rc0</code> release candidate introduced a regression via [PR #2705] that has been reverted in <code>rc1</code> and later via [PR #2789]. Further investigation is needed to determine how to accomplish the goal of [PR #2705] (\"feat: inject profile\") without the regression. The <code>rc2</code> and later releases address a regression related to the sending of a revocation notification from the issuer to the holder of a newly revoked credential, fixed in [PR #2814]</p> <p>Much progress has been made on <code>did:peer</code> support in this release, with the handling of inbound DID Peer 1 added, and inbound and outbound support for DID Peer 2 and 4. The goal of that work is to eliminate the remaining places where \"unqualified\" DIDs remain, and to enable the \"connection reuse\" in the Out of Band protocol when using DID Peer 2 and 4 DIDs. Work continues in supporting ledger agnostic AnonCreds, and the new Hyperledger AnonCreds Rust library. Attention was also given in the release to the handling of JSON-LD Data Integrity Verifiable Credentials, with more expected before the release is finalized. In addition to those updates, there were fixes and improvements across the codebase.</p> <p>The most visible change in this release is the re-organization of the ACA-Py documentation, moving the vast majority of the documents to the folders within the <code>docs</code> folder -- a long overdue change that will allow us to soon publish the documents on https://aca-py.org directly from the ACA-Py repository, rather than from the separate aries-acapy-docs currently being used.</p> <p>A big developer improvement is a revamping of the test handling to eliminate ~2500 warnings that were previously generated in the test suite.  Nice job @ff137!</p>"},{"location":"CHANGELOG/#0120rc2-breaking-changes","title":"0.12.0rc2 Breaking Changes","text":"<p>There are no breaking changes in 0.12.0rc2.</p>"},{"location":"CHANGELOG/#0120rc2-categorized-list-of-pull-requests","title":"0.12.0rc2 Categorized List of Pull Requests","text":"<ul> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>Author subwallet setup automation #2791 jamshale</li> <li>fix: save multi_use to the DB for OOB invitations #2694 frostyfrog</li> <li> <p>Connection and DIDX Problem Reports #2653 usingtechnology</p> </li> <li> <p>DID Peer and DID Resolver Updates and Fixes</p> </li> <li>Integration test for did:peer #2713 ianco</li> <li>Feature/emit did peer 4 #2696 Jsyro</li> <li>did peer 4 resolution #2692 Jsyro</li> <li>Emit did:peer:2 for didexchange #2687 Jsyro</li> <li>Add did web method type as a default option #2684 PatStLouis</li> <li>feat: add did:jwk resolver #2645 dbluhm</li> <li> <p>feat: support resolving did:peer:1 received in did exchange #2611 dbluhm</p> </li> <li> <p>Ledger Agnostic AnonCreds RS Changes</p> </li> <li>Send revocation list instead of rev_list object - Anoncreds #2821 jamshale</li> <li>Fix anoncreds non-endorsement revocation #2814 jamshale  - Get and create anoncreds profile when using anoncreds subwallet #2803 jamshale</li> <li>Add anoncreds multitenant endorsement integration tests #2801 jamshale</li> <li>Anoncreds revoke and publish-revocations endorsement #2782 jamshale</li> <li>Upgrade anoncreds to version 0.2.0-dev11 #2763 jamshale</li> <li>Update anoncreds to 0.2.0-dev10 #2758 jamshale</li> <li>Anoncreds - Cred Def and Revocation Endorsement #2752 jamshale</li> <li>Upgrade anoncreds to 0.2.0-dev9 #2741 jamshale</li> <li>Upgrade anoncred-rs to version 0.2.0-dev8 #2734 jamshale</li> <li>Upgrade anoncreds to 0.2.0.dev7 #2719 jamshale</li> <li>Improve api documentation and error handling #2690 jamshale</li> <li>Add unit tests for anoncreds revocation #2688 jamshale</li> <li>Return 404 when schema not found #2683 jamshale</li> <li>Anoncreds - Add unit testing #2672 jamshale</li> <li>Additional anoncreds integration tests  AnonCreds #2660 ianco</li> <li>Update integration tests for anoncreds-rs  AnonCreds #2651 ianco</li> <li>Initial migration of anoncreds revocation code  AnonCreds #2643 ianco</li> <li>Integrate Anoncreds rs into credential and presentation endpoints  AnonCreds #2632 ianco</li> <li> <p>Initial code migration from anoncreds-rs branch  AnonCreds #2596 ianco</p> </li> <li> <p>Hyperledger Indy ledger related updates and fixes</p> </li> <li>Add known issues section to Multiledger.md documentation #2788 esune</li> <li>fix: update constants in TransactionRecord #2698 amanji</li> <li>Cache TAA by wallet name #2676 jamshale</li> <li> <p>Fix: RevRegEntry Transaction Endorsement  0.11.0 #2558 shaangill025</p> </li> <li> <p>JSON-LD Verifiable Credential/DIF Presentation Exchange updates</p> </li> <li>Revert profile injection for VcLdpManager on vc-api endpoints #2794 PatStLouis</li> <li>Add cached copy of BBS v1 context #2749 andrewwhitehead</li> <li>Update BBS+ context to bypass redirections #2739 swcurran</li> <li>feat: make VcLdpManager pluggable #2706 dbluhm</li> <li>fix: minor type hint corrections for VcLdpManager #2704 dbluhm</li> <li>Remove if condition which checks if the credential.type array is equal to 1 #2670 PatStLouis</li> <li>Feature Suggestion: Include a Reason When Constraints Cannot Be Applied #2630 Ennovate-com</li> <li> <p>refactor: make ldp_vc logic reusable #2533 dbluhm</p> </li> <li> <p>Credential Exchange (Issue, Present) Updates</p> </li> <li>Allow for crids in event payload to be integers #2819 jamshale  - Create revocation notification after list entry written to ledger #2812 jamshale</li> <li>Remove exception on connectionless presentation problem report handler #2723 loneil</li> <li>Ensure \"preserve_exchange_records\" flags are set. #2664 usingtechnology</li> <li>Slight improvement to credx proof validation error message #2655 ianco</li> <li> <p>Add ConnectionProblemReport handler #2600 usingtechnology</p> </li> <li> <p>Multitenancy Updates and Fixes</p> </li> <li>feature/per tenant settings #2790 amanji</li> <li> <p>Improve Per Tenant Logging: Fix issues around default log file path #2659 shaangill025</p> </li> <li> <p>Other Fixes, Demo, DevContainer and Documentation Fixes</p> </li> <li>FIX: GHA update for doc publishing, fix doc file that was blanked #2820 swcurran</li> <li>More updates to get docs publishing #2810 swcurran</li> <li>Eliminate the double workflow event #2811 swcurran</li> <li>Publish docs GHActions tweak #2806 swcurran</li> <li>Update publish-docs to operate on main and on branches prefixed with docs-v #2804 swcurran</li> <li>Add index.html redirector to gh-pages branch #2802 swcurran</li> <li>Demo description of reuse in establishing a connection #2787 swcurran</li> <li>Reorganize the ACA-Py Documentation Files #2765 swcurran</li> <li>Tweaks to MD files to enable aca-py.org publishing #2771 swcurran</li> <li>Update devcontainer documentation #2729 jamshale</li> <li>Update the SupportedRFCs Document to be up to date #2722 swcurran</li> <li>Fix incorrect Sphinx search library version reference #2716 swcurran</li> <li>Update RTD requirements after security vulnerability recorded #2712 swcurran</li> <li>Update legacy bcgovimages references. #2700 WadeBarnes</li> <li>fix: link to raw content change from master to main #2663 Ennovate-com</li> <li>fix: open-api generator script #2661 dbluhm</li> <li> <p>Update the ReadTheDocs config in case we do another 0.10.x release #2629 swcurran</p> </li> <li> <p>Dependencies and Internal Updates</p> </li> <li>bot    chore(deps): Bump cryptography from 42.0.3 to 42.0.4  dependencies python #2805 dependabot</li> <li>bot    chore(deps): Bump the all-actions group with 3 updates  dependencies github_actions #2815 dependabot</li> <li>Change middleware registration order #2796 PatStLouis</li> <li>Bump pyld version to 2.0.4 #2795 PatStLouis</li> <li>Revert profile inject #2789 jamshale</li> <li>Move emit events to profile and delay sending until after commit #2760 ianco</li> <li>fix: partial revert of ConnRecord schema change  1.0.0 #2746 dbluhm</li> <li>chore(deps): Bump aiohttp from 3.9.1 to 3.9.2  dependencies #2745 dependabot bot</li> <li>bump pydid to v 0.4.3 #2737 PatStLouis</li> <li>Fix subwallet record removal #2721 andrewwhitehead</li> <li>chore(deps): Bump jinja2 from 3.1.2 to 3.1.3  dependencies #2707 dependabot bot</li> <li>feat: inject profile #2705 dbluhm</li> <li>Remove tiny-vim from being added to the container image to reduce reported vulnerabilities from scanning #2699 swcurran</li> <li>chore(deps): Bump jwcrypto from 1.5.0 to 1.5.1  dependencies #2689 dependabot bot</li> <li>Update dependencies #2686 andrewwhitehead</li> <li>Fix: Change To Use Timezone Aware UTC datetime #2679 Ennovate-com</li> <li>fix: update broken demo dependency #2638 mrkaurelius</li> <li>Bump cryptography from 41.0.5 to 41.0.6  dependencies #2636 dependabot bot</li> <li> <p>Bump aiohttp from 3.8.6 to 3.9.0  dependencies #2635 dependabot bot</p> </li> <li> <p>CI/CD, Testing, and Developer Tools/Productivity Updates</p> </li> <li>Fix deprecation warnings #2756 ff137</li> <li>chore(deps): Bump the all-actions group with 10 updates  dependencies #2784 dependabot bot</li> <li>Add Dependabot configuration #2783 WadeBarnes</li> <li>Implement B006 rule #2775 jamshale</li> <li>\u2b06\ufe0f Upgrade pytest to 8.0 #2773 ff137</li> <li>\u2b06\ufe0f Update pytest-asyncio to 0.23.4 #2764 ff137</li> <li>Remove asynctest dependency and fix \"coroutine not awaited\" warnings #2755 ff137</li> <li>Fix pytest collection errors when anoncreds package is not installed #2750 andrewwhitehead</li> <li>chore: pin black version #2747 dbluhm</li> <li>Tweak scope of GHA integration tests #2662 ianco</li> <li> <p>Update snyk workflow to execute on Pull Request #2658 usingtechnology</p> </li> <li> <p>Release management pull requests</p> </li> <li>0.12.0rc2 #2825 swcurran</li> <li>0.12.0rc1 #2800 swcurran</li> <li>0.12.0rc1 #2799 swcurran</li> <li>0.12.0rc0 #2732 swcurran</li> </ul>"},{"location":"CHANGELOG/#0110","title":"0.11.0","text":""},{"location":"CHANGELOG/#november-24-2023","title":"November 24, 2023","text":"<p>Release 0.11.0 is a relatively large release of new features, fixes, and internal updates. 0.11.0 is planned to be the last significant update before we begin the transition to using the ledger agnostic AnonCreds Rust in a release that is expected to bring Admin/Controller API changes. We plan to do patches to the 0.11.x branch while the transition is made to using [Anoncreds Rust].</p> <p>An important addition to ACA-Py is support for signing and verifying SD-JWT verifiable credentials. We expect this to be the first of the changes to extend ACA-Py to support OpenID4VC protocols.</p> <p>This release and Release 0.10.5 contain a high priority fix to correct an issue with the handling of the JSON-LD presentation verifications, where the status of the verification of the <code>presentation.proof</code> in the Verifiable Presentation was not included when determining the verification value (<code>true</code> or <code>false</code>) of the overall presentation. A forthcoming security advisory will cover the details. Anyone using JSON-LD presentations is recommended to upgrade to one of these versions of ACA-Py as soon as possible.</p> <p>In the CI/CD realm, substantial changes were applied to the source base in switching from:</p> <ul> <li><code>pip</code> to Poetry for packaging and dependency management,</li> <li>Flake8 to Ruff for linting,</li> <li><code>asynctest</code> to <code>IsolatedAsyncioTestCase</code> and <code>AsyncMock</code> objects now included in Python's builtin <code>unittest</code> package for unit testing.</li> </ul> <p>These are necessary and important modernization changes, with the latter two triggering many (largely mechanical) changes to the codebase.</p>"},{"location":"CHANGELOG/#0110-breaking-changes","title":"0.11.0 Breaking Changes","text":"<p>In addition to the impacts of the change for developers in switching from <code>pip</code> to Poetry, the only significant breaking change is the (overdue) transition of ACA-Py to always use the new DIDComm message type prefix, changing the DID Message prefix from the old hardcoded <code>did:sov:BzCbsNYhMrjHiqZDTUASHg;spec</code> to the new hardcoded <code>https://didcomm.org</code> value, and using the new DIDComm MIME type in place of the old. The vast majority (all?) Aries deployments have long since been updated to accept both values, so this change just forces the use of the newer value in sending messages. In updating this, we retained the old configuration parameters most deployments were using (<code>--emit-new-didcomm-prefix</code> and <code>--emit-new-didcomm-mime-type</code>) but updated the code to set the configuration parameters to <code>true</code> even if the parameters were not set. See [PR #2517].</p> <p>The JSON-LD verifiable credential handling of JSON-LD contexts has been updated to pre-load the base contexts into the repository code so they are not fetched at run time. This is a security best practice for JSON-LD, and prevents errors in production when, from time to time, the JSON-LD contexts are unavailable because of outages of the web servers where they are hosted. See [PR #2587].</p> <p>A Problem Report message is now sent when a request for a credential is received and there is no associated Credential Exchange Record. This may happen, for example, if an issuer decides to delete a Credential Exchange Record that has not be answered for a long time, and the holder responds after the delete. See [PR #2577].</p>"},{"location":"CHANGELOG/#0110-categorized-list-of-pull-requests","title":"0.11.0 Categorized List of Pull Requests","text":"<ul> <li>DIDComm Messaging Improvements/Fixes</li> <li>Change arg_parse to always set --emit-new-didcomm-prefix and --emit-new-didcomm-mime-type to true #2517 swcurran</li> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>Goal and Goal Code in invitation URL. #2591 usingtechnology</li> <li>refactor: use did-peer-2 instead of peerdid #2561 dbluhm</li> <li>Fix: Problem Report Before Exchange Established #2519 Ennovate-com</li> <li>fix: issue #2434: Change DIDExchange States to Match rfc160 #2461 anwalker293</li> <li>DID Peer and DID Resolver Updates and Fixes</li> <li>fix: unique ids for services in legacy peer #2476 dbluhm</li> <li>peer did \u2154 resolution  enhancement #2472 Jsyro</li> <li>feat: add timeout to did resolver resolve method #2464 dbluhm</li> <li>ACA-Py as a DIDComm Mediator Updates and Fixes</li> <li>fix: routing behind mediator #2536 dbluhm</li> <li>fix: mediation routing keys as did key #2516 dbluhm</li> <li>refactor: drop mediator_terms and recipient_terms #2515 dbluhm</li> <li>Fixes to Upgrades</li> <li>\ud83d\udc1b fix wallet_update when only extra_settings requested #2612 ff137</li> <li>Hyperledger Indy ledger related updates and fixes</li> <li>fix: taa rough timestamp timezone from datetime #2554 dbluhm</li> <li>\ud83c\udfa8 clarify LedgerError message when TAA is required and not accepted #2545 ff137</li> <li>Feat: Upgrade from tags and fix issue with legacy IssuerRevRegRecords [&lt;=v0.5.2] #2486 shaangill025</li> <li>Bugfix: Issue with write ledger pool when performing Accumulator sync #2480 shaangill025</li> <li>Issue #2419 InvalidClientTaaAcceptanceError time too precise error if container timezone is not UTC #2420 Ennovate-com</li> <li>OpenID4VC / SD-JWT Updates</li> <li>chore: point to official sd-jwt lib release #2573 dbluhm</li> <li>Feat/sd jwt implementation #2487 cjhowland</li> <li>JSON-LD Verifiable Credential/Presentation updates</li> <li>fix: report presentation result #2615 dbluhm</li> <li>Fix Issue #2589 TypeError When There Are No Nested Requirements #2590 Ennovate-com</li> <li>feat: use a local static cache for commonly used contexts #2587 chumbert</li> <li>Issue #2488 KeyError raised when Subject ID is not a URI #2490 Ennovate-com</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Default connection_id to None to account for Connectionless Proofs #2605 popkinj</li> <li>Send Problem report when CredEx not found #2577 usingtechnology</li> <li>fix: clean up requests and invites #2560 dbluhm</li> <li>Multitenancy Updates and Fixes</li> <li>Feat: Support subwallet upgradation using the Upgrade command #2529 shaangill025</li> <li>Other Fixes, Demo, DevContainer and Documentation Fixes</li> <li>fix: wallet type help text out of date #2618 dbluhm</li> <li>fix: typos #2614 omahs</li> <li>black formatter extension configuration update #2603 usingtechnology</li> <li>Update Devcontainer pytest ruff black #2602 usingtechnology</li> <li>Issue 2570 devcontainer ruff, black and pytest #2595 usingtechnology</li> <li>chore: correct type hints on base record #2604 dbluhm</li> <li>Playground needs optionally external network #2564 usingtechnology</li> <li>Issue 2555 playground scripts readme #2563 usingtechnology</li> <li>Update demo/playground scripts #2562 usingtechnology</li> <li>Update .readthedocs.yaml #2548 swcurran</li> <li>Update .readthedocs.yaml #2547 swcurran</li> <li>fix: correct minor typos #2544 Ennovate-com</li> <li>Update steps for Manually Creating Revocation Registries #2491 WadeBarnes</li> <li>Dependencies and Internal Updates</li> <li>chore: bump pydid version #2626 dbluhm</li> <li>chore: dependency updates #2565 dbluhm</li> <li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7  dependencies #2552 dependabot bot</li> <li>chore(deps): Bump urllib3 from 2.0.6 to 2.0.7 in /demo/playground/scripts  dependencies #2551 dependabot bot</li> <li>chore: update pydid #2527 dbluhm</li> <li>chore(deps): Bump urllib3 from 2.0.5 to 2.0.6  dependencies #2525 dependabot bot</li> <li>chore(deps): Bump urllib3 from 2.0.2 to 2.0.6 in /demo/playground/scripts  dependencies #2524 dependabot bot</li> <li>Avoid multiple open wallet connections #2521 andrewwhitehead</li> <li>Remove unused dependencies #2510 andrewwhitehead</li> <li>Use correct rust log level in dockerfiles #2499 loneil</li> <li>fix: run tests script copying local env #2495 dbluhm</li> <li>Update devcontainer to read version from aries-cloudagent package #2483 usingtechnology</li> <li>Update Python image version to 3.9.18 #2456 WadeBarnes</li> <li>Remove old routing protocol code #2466 dbluhm</li> <li>CI/CD, Testing, and Developer Tools/Productivity Updates</li> <li>fix: drop asynctest  0.11.0 #2566 dbluhm</li> <li>Dockerfile.indy - Include aries_cloudagent code into build #2584 usingtechnology</li> <li>fix: version should be set by pyproject.toml #2471 dbluhm</li> <li>chore: add black back in as a dev dep #2465 dbluhm</li> <li>Swap out flake8 in favor of Ruff #2438 dbluhm</li> <li> </li> <li>Release management pull requests</li> <li>0.11.0 #2627 swcurran</li> <li>0.11.0rc2 #2613 swcurran</li> <li>0.11.0-rc1 #2576 swcurran</li> <li>0.11.0-rc0 #2575 swcurran</li> </ul>"},{"location":"CHANGELOG/#2289-migrate-to-poetry-2436-gavinok","title":"2289 Migrate to Poetry #2436 Gavinok","text":""},{"location":"CHANGELOG/#0105","title":"0.10.5","text":""},{"location":"CHANGELOG/#november-21-2023","title":"November 21, 2023","text":"<p>Release 0.10.5 is a high priority patch release to correct an issue with the handling of the JSON-LD presentation verifications, where the status of the verification of the <code>presentation.proof</code> in the Verifiable Presentation was not included when determining the verification value (<code>true</code> or <code>false</code>) of the overall presentation. A forthcoming security advisory will cover the details.</p> <p>Anyone using JSON-LD presentations is recommended to upgrade to this version of ACA-Py as soon as possible.</p>"},{"location":"CHANGELOG/#0105-categorized-list-of-pull-requests","title":"0.10.5 Categorized List of Pull Requests","text":"<ul> <li>JSON-LD Credential Exchange (Issue, Present) Updates</li> <li>fix(backport): report presentation result #2622 dbluhm</li> <li>Release management pull requests</li> <li>0.10.5 #2623 swcurran</li> </ul>"},{"location":"CHANGELOG/#0104","title":"0.10.4","text":""},{"location":"CHANGELOG/#october-9-2023","title":"October 9, 2023","text":"<p>Release 0.10.4 is a patch release to correct an issue with the handling of <code>did:key</code> routing keys in some mediator scenarios, notably with the use of [Aries Framework Kotlin]. See the details in the PR and [Issue #2531 Routing for agents behind a aca-py based mediator is broken].</p> <p>Thanks to codespree for raising the issue and providing the fix.</p> <p>Aries Framework Kotlin</p>"},{"location":"CHANGELOG/#0104-categorized-list-of-pull-requests","title":"0.10.4 Categorized List of Pull Requests","text":"<ul> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>fix: routing behind mediator #2536 dbluhm</li> <li>Release management pull requests</li> <li>0.10.4 #2539 swcurran</li> </ul>"},{"location":"CHANGELOG/#0103","title":"0.10.3","text":""},{"location":"CHANGELOG/#september-29-2023","title":"September 29, 2023","text":"<p>Release 0.10.3 is a patch release to add an upgrade process for very old versions of Aries Cloud Agent Python (circa 0.5.2). If you have a long time deployment of an issuer that uses revocation, this release could correct internal data (tags in secure storage) related to revocation registries. Details of the about the triggering problem can be found in [Issue #2485].</p> <p>The upgrade is applied by running the following command for the ACA-Py instance to be upgraded:</p> <p><code>./scripts/run_docker upgrade --force-upgrade --named-tag fix_issue_rev_reg</code></p>"},{"location":"CHANGELOG/#0103-categorized-list-of-pull-requests","title":"0.10.3 Categorized List of Pull Requests","text":"<ul> <li>Credential Exchange (Issue, Present) Updates</li> <li>Feat: Upgrade from tags and fix issue with legacy IssuerRevRegRecords [&lt;=v0.5.2] #2486 shaangill025</li> <li>Release management pull requests</li> <li>0.10.3 #2522 swcurran</li> </ul>"},{"location":"CHANGELOG/#0102","title":"0.10.2","text":""},{"location":"CHANGELOG/#september-22-2023","title":"September 22, 2023","text":"<p>Release 0.10.2 is a patch release for 0.10.1 that addresses three specific regressions found in deploying Release 0.10.1. The regressions are to fix:</p> <ul> <li>An ACA-Py instance upgraded to 0.10.1 that had an existing connection to another Aries agent where the connection has both an <code>http</code> and <code>ws</code> (websocket) service endpoint with the same ID cannot message that agent. A scenario is an ACA-Py issuer connecting to an Endorser with both <code>http</code> and <code>ws</code> service endpoints. The updates made in 0.10.1 to improve ACA-Py DID resolution did not account for this scenario and needed a tweak to work ([Issue #2474], [PR #2475]).</li> <li>The \"fix revocation registry\" endpoint used to fix scenarios an Issuer's local revocation registry state is out of sync with the ledger was broken by some code being added to support a single ACA-Py instance writing to different ledgers ([Issue #2477], [PR #2480]).</li> <li>The version of the PyDID library we were using did not handle some unexpected DID resolution use cases encountered with mediators. The PyDID library version dependency was updated in [PR #2500].</li> </ul>"},{"location":"CHANGELOG/#0102-categorized-list-of-pull-requests","title":"0.10.2 Categorized List of Pull Requests","text":"<ul> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>LegacyPeerDIDResolver: erroneously assigning same ID to multiple services #2475 dbluhm</li> <li>fix: update pydid #2500 dbluhm</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Bugfix: Issue with write ledger pool when performing Accumulator sync #2480 shaangill025</li> <li>Release management pull requests</li> <li>0.10.2 #2509 swcurran</li> <li>0.10.2-rc0 #2484 swcurran</li> <li>0.10.2 Patch Release - fix issue #2475, #2477 #2482 shaangill025</li> </ul>"},{"location":"CHANGELOG/#0101","title":"0.10.1","text":""},{"location":"CHANGELOG/#august-29-2023","title":"August 29, 2023","text":"<p>Release 0.10.1 contains a breaking change, an important fix for a regression introduced in 0.8.2 that impacts certain deployments, and a number of fixes and updates. Included in the updates is a significant internal reorganization of the DID and connection management code that was done to enable more flexible uses of different DID Methods, such as being able to use <code>did:web</code> DIDs for DIDComm messaging connections. The work also paves the way for coming updates related to support for <code>did:peer</code> DIDs for DIDComm. For details on the change see [PR #2409], which includes some of the best pull request documentation ever created.</p> <p>Release 0.10.1 has the same contents as 0.10.0. An error on PyPi prevented the 0.10.0 release from being properly uploaded because of an existing file of the same name. We immediately released 0.10.1 as a replacement.</p> <p>The regression fix is for ACA-Py deployments that use multi-use invitations but do NOT use the <code>--auto-accept-connection-requests</code> flag/processing. A change in 0.8.2 (PR [#2223]) suppressed an extra webhook event firing during the processing after receiving a connection request. An unexpected side effect of that change was that the subsequent webhook event also did not fire, and as a result, the controller did not get any event signalling a new connection request had been received via the multi-use invitation. The update in this release ensures the proper event fires and the controller receives the webhook.</p> <p>See below for the breaking changes and a categorized list of the pull requests included in this release.</p> <p>Updates in the CI/CD area include adding the publishing of a <code>nightly</code> container image that includes any changes in the main branch since the last <code>nightly</code> was published. This allows getting the \"latest and greatest\" code via a container image vs. having to install ACA-Py from the repository. In addition, Snyk scanning was added to the CI pipeline, and Indy SDK tests were removed from the pipeline.</p>"},{"location":"CHANGELOG/#0101-breaking-changes","title":"0.10.1 Breaking Changes","text":"<p>[#2352] is a breaking change related to the storage of presentation exchange records in ACA-Py. In previous releases, presentation exchange protocol state data records were retained in ACA-Py secure storage after the completion of protocol instances. With this release the default behavior changes to deleting those records by default, unless the <code>----preserve-exchange-records</code> flag is set in the configuration. This extends the use of that flag that previously applied only to issue credential records. The extension matches the initial intention of the flag--that it cover both issue credential and present proof exchanges. The \"best practices\" for ACA-Py is that the controller (business logic) store any long-lasting business information needed for the service that is using the Aries Agent, and ACA-Py storage should be used only for data necessary for the operation of the agent. In particular, protocol state data should be held in ACA-Py only as long as the protocol is running (as it is needed by ACA-Py), and once a protocol instance completes, the controller should extract and store the business information from the protocol state before it is deleted from ACA-Py storage.</p>"},{"location":"CHANGELOG/#0100-categorized-list-of-pull-requests","title":"0.10.0 Categorized List of Pull Requests","text":"<ul> <li>DIDComm Messaging Improvements/Fixes</li> <li>fix: outbound send status missing on path #2393 dbluhm</li> <li>fix: keylist update response race condition #2391 dbluhm</li> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>fix: handle stored afgo and findy docs in corrections #2450 dbluhm</li> <li>chore: relax connections filter DID format #2451 chumbert</li> <li>fix: ignore duplicate record errors on add key #2447 dbluhm</li> <li>fix: ignore duplicate record errors on add key #2447 dbluhm</li> <li>fix: more diddoc corrections #2446 dbluhm</li> <li>feat: resolve connection targets and permit connecting via public DID #2409 dbluhm</li> <li>feat: add legacy peer did resolver #2404 dbluhm</li> <li>Fix: Ensure event/webhook is emitted for multi-use invitations #2413 esune</li> <li>feat: add DID Exchange specific problem reports and reject endpoint #2394 dbluhm</li> <li>fix: additional tweaks for did:web and other methods as public DIDs #2392 dbluhm</li> <li>Fix empty ServiceDecorator in OobRecord causing 422 Unprocessable Entity Error #2362 ff137</li> <li>Feat: Added support for Ed25519Signature2020 signature type and Ed25519VerificationKey2020 #2241 dkulic</li> <li>Upgrading to Aries Askar Updates</li> <li>Add symlink to /home/indy/.indy_client for backwards compatibility #2443 esune</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>fix: ensure request matches offer in JSON-LD exchanges, if sent #2341 dbluhm</li> <li>BREAKING Extend --preserve-exchange-records to include Presentation Exchange. #2352 usingtechnology</li> <li>Correct the response type in send_rev_reg_def #2355 ff137</li> <li>Multitenancy Updates and Fixes</li> <li>Multitenant check endorser_info before saving #2395 usingtechnology</li> <li>Feat: Support Selectable Write Ledger #2339 shaangill025</li> <li>Other Fixes, Demo, and Documentation Fixes</li> <li>Redis Plugins [redis_cache &amp; redis_queue] documentation and docker related updates #1937 shaangill025</li> <li>Chore: fix marshmallow warnings #2398 ff137</li> <li>Upgrade pre-commit and flake8 dependencies; fix flake8 warnings #2399 ff137</li> <li>Corrected typo on mediator invitation configuration argument #2365 jorgefl0</li> <li>Add workaround for ARM based macs #2313 finnformica</li> <li>Dependencies and Internal Updates</li> <li>chore(deps): Bump certifi from 2023.5.7 to 2023.7.22 in /demo/playground/scripts dependencies #2354 dependabot bot</li> <li>CI/CD and Developer Tools/Productivity Updates</li> <li>Fix for nightly tests failing on Python 3.10 #2435 Gavinok</li> <li>Don't run Snyk on forks #2429 ryjones</li> <li>Issue #2250 Nightly publish workflow #2421 Gavinok</li> <li>Enable Snyk scanning #2418 ryjones</li> <li>Remove Indy tests from workflows #2415 dbluhm</li> <li>Release management pull requests</li> <li>0.10.1 #2454 swcurran</li> <li>0.10.0 #2452 swcurran</li> <li>0.10.0-rc2 #2448 swcurran</li> <li>0.10.0-rc1 #2442 swcurran</li> <li>0.10.0-rc0 #2414 swcurran</li> </ul>"},{"location":"CHANGELOG/#0100","title":"0.10.0","text":""},{"location":"CHANGELOG/#august-29-2023_1","title":"August 29, 2023","text":"<p>Release 0.10.1 has the same contents as 0.10.0. An error on PyPi prevented the 0.10.0 release from being properly uploaded because of an existing file of the same name. We immediately released 0.10.1 as a replacement.</p>"},{"location":"CHANGELOG/#090","title":"0.9.0","text":""},{"location":"CHANGELOG/#july-24-2023","title":"July 24, 2023","text":"<p>Release 0.9.0 is an important upgrade that changes (PR [#2302]) the dependency on the now archived Hyperledger Ursa project to its updated, improved replacement, AnonCreds CL-Signatures. This important change is ONLY available when using Aries Askar as the wallet type, which brings in both [Indy VDR] and the CL-Signatures via the latest version of CredX from the indy-shared-rs repository. The update is NOT available to those that are using the Indy SDK. All new deployments of ACA-Py SHOULD use Aries Askar. Further, we strongly recommend that all deployments using the Indy SDK with ACA-Py upgrade their installation to use Aries Askar and the related components using the migration scripts available. An Indy SDK to Askar migration document added to the aca-py.org documentation site, and a deprecation warning added to the ACA-Py startup.</p> <p>The second big change in this release is that we have upgraded the primary Python version from 3.6 to 3.9 (PR [#2247]). In this case, primary means that Python 3.9 is used to run the unit and integration tests on all Pull Requests. We also do nightly runs of the main branch using Python 3.10. As of this release we have dropped Python 3.6, 3.7 and 3.8, and introduced new dependencies that are not supported in those versions of Python. For those that use the published ACA-Py container images, the upgrade should be easily handled. If you are pulling ACA-Py into your own image, or a non-containerized environment, this is a breaking change that you will need to address.</p> <p>Please see the next section for all breaking changes, and the subsequent section for a categorized list of all pull requests in this release.</p>"},{"location":"CHANGELOG/#breaking-changes","title":"Breaking Changes","text":"<p>In addition to the breaking Python 3.6 to 3.9 upgrade, there are two other breaking changes that may impact some deployments.</p> <p>[#2034] allows for additional flexibility in using public DIDs in invitations, and adds a restriction that \"implicit\" invitations must be proactively enabled using a flag (<code>--requests-through-public-did</code>). Previously, such requests would always be accepted if <code>--auto-accept</code> was enabled, which could lead to unexpected connections being established.</p> <p>[#2170] is a change to improve message handling in the face of delivery errors when using a persistent queue implementation such as the ACA-Py Redis Plugin. If you are using the Redis plugin, you MUST upgrade to Redis Plugin Release 0.1.0 in conjunction with deploying this ACA-Py release. For those using their own persistent queue solution, see the PR [#2170] comments for information about changes you might need to make to your deployment.</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests","title":"Categorized List of Pull Requests","text":"<ul> <li>DIDComm Messaging Improvements/Fixes</li> <li>BREAKING: feat: get queued outbound message in transport handle message #2170 dbluhm</li> <li>DID Handling and Connection Establishment Updates/Fixes</li> <li>Allow any did to be public #2295 mkempa</li> <li>Feat: Added support for Ed25519Signature2020 signature type and Ed25519VerificationKey2020 #2241 dkulic</li> <li>Add Goal and Goal Code to OOB and DIDex Request #2294 usingtechnology</li> <li>Fix routing in set public did #2288 mkempa  - Fix: Do not replace public verkey on mediator #2269 mkempa  - BREAKING: Allow multi-use public invites and public invites with metadata #2034 mepeltier</li> <li>fix: public did mediator routing keys as did keys #1977 dbluhm</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Add revocation registry rotate to faber demo #2333 usingtechnology</li> <li>Update to indy-credx 1.0 #2302 andrewwhitehead</li> <li>feat(anoncreds): Implement automated setup of revocation #2292 dbluhm</li> <li>fix: schema class can set Meta.unknown #1885 dbluhm</li> <li>Respect auto-verify-presentation flag in present proof v1 and v2 #2097 dbluhm</li> <li>Feature: JWT Sign and Verify Admin Endpoints with DID Support #2300 burdettadam</li> <li>Multitenancy Updates and Fixes</li> <li>Fix: Track endorser and author roles in per-tenant settings #2331 shaangill025</li> <li>Added base wallet provisioning details to Multitenancy.md #2328 esune</li> <li>Other Fixes, Demo, and Documentation Fixes</li> <li>Add more context to the ACA-Py Revocation handling documentation #2343 swcurran</li> <li>Document the Indy SDK to Askar Migration process #2340 swcurran</li> <li>Add revocation registry rotate to faber demo #2333 usingtechnology</li> <li>chore: add indy deprecation warnings #2332 dbluhm</li> <li>Fix alice/faber demo execution #2305 andrewwhitehead</li> <li>Add .indy_client folder to Askar only image. #2308 WadeBarnes</li> <li>Add build step for indy-base image in run_demo #2299 usingtechnology</li> <li>Webhook over websocket clarification #2287 dbluhm</li> <li>ACA-Py Deployment Upgrade Changes</li> <li>Add Explicit/Offline marking mechanism for Upgrade #2204 shaangill025</li> <li>Plugin Handling Updates</li> <li>Feature: Add the ability to deny specific plugins from loading  0.7.4 #1737 frostyfrog</li> <li>Dependencies and Internal Updates</li> <li>upgrade pyjwt to latest; introduce leeway to jwt.decodet #2335 ff137</li> <li>upgrade requests to latest #2336 ff137</li> <li>upgrade packaging to latest #2334 ff137</li> <li>chore: update PyYAML #2329 dbluhm</li> <li>chore(deps): Bump aiohttp from 3.8.4 to 3.8.5 in /demo/playground/scripts dependencies #2325 dependabot bot</li> <li>\u2b06\ufe0f upgrade marshmallow to latest #2322 ff137</li> <li>fix: use python 3.9 in run_docker #2291 dbluhm</li> <li>BREAKING!: drop python 3.6 support #2247 dbluhm</li> <li>Minor revisions to the README.md and DevReadMe.md #2272 swcurran</li> <li>ACA-Py Administrative Updates</li> <li>Updating Maintainers list to be accurate and using the TOC format #2258 swcurran</li> <li>CI/CD and Developer Tools/Productivity Updates</li> <li>Cancel in-progress workflows when PR is updated #2303 andrewwhitehead</li> <li>ci: add gha for pr-tests #2058 dbluhm</li> <li>Add devcontainer for ACA-Py #2267 usingtechnology</li> <li>Docker images and GHA for publishing images  help wanted #2076 dbluhm</li> <li>ci: test additional versions of python nightly #2059 dbluhm</li> <li>Release management pull requests</li> <li>0.9.0 #2344 swcurran</li> <li>0.9.0-rc0 #2338 swcurran</li> </ul>"},{"location":"CHANGELOG/#082","title":"0.8.2","text":""},{"location":"CHANGELOG/#june-29-2023","title":"June 29, 2023","text":"<p>Release 0.8.2 contains a number of minor fixes and updates to ACA-Py, including the correction of a regression in Release 0.8.0 related to the use of plugins (see [#2255]). Highlights include making it easier to use tracing in a development environment to collect detailed performance information about what is going in within ACA-Py.</p> <p>This release pulls in indy-shared-rs Release 3.3 which fixes a serious issue in AnonCreds verification, as described in issue [#2036], where the verification of a presentation with multiple revocable credentials fails when using Aries Askar and the other shared components. This issue occurs only when using Aries Askar and indy-credx Release 3.3.</p> <p>An important new feature in this release is the ability to set some instance configuration settings at the tenant level of a multi-tenant deployment. See PR [#2233].</p> <p>There are no breaking changes in this release.</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_1","title":"Categorized List of Pull Requests","text":"<ul> <li>Connections Fixes/Updates</li> <li>Resolve definitions.py fix to fix backwards compatibility break in plugins #2255 usingtechnology</li> <li>Add support for JsonWebKey2020 for the connection invitations #2173 dkulic</li> <li>fix: only cache completed connection targets #2240 dbluhm</li> <li>Connection target should not be limited only to indy dids #2229 dkulic</li> <li>Disable webhook trigger on initial response to multi-use connection invitation #2223 esune</li> <li>Credential Exchange (Issue, Present) Updates</li> <li>Pass document loader to jsonld.expand #2175 andrewwhitehead</li> <li>Multi-tenancy fixes/updates</li> <li>Allow Configuration Settings on a per-tenant basis #2233 shaangill025</li> <li>stand up multiple agents (single and multi) for local development and testing #2230 usingtechnology</li> <li>Multi-tenant self-managed mediation verkey lookup #2232 usingtechnology</li> <li>fix: route multitenant connectionless oob invitation #2243 TimoGlastra</li> <li>Fix multitenant/mediation in demo #2075 ianco</li> <li>Other Bug and Documentation Fixes</li> <li>Assign ~thread.thid with thread_id value #2261 usingtechnology</li> <li>Fix: Do not replace public verkey on mediator #2269 mkempa</li> <li>Provide an optional Profile to the verification key strategy #2265 yvgny</li> <li>refactor: Extract verification method ID generation to a separate class #2235 yvgny</li> <li>Create .readthedocs.yaml file #2268 swcurran</li> <li>feat(did creation route): reject unregistered did methods #2262 chumbert</li> <li>./run_demo performance -c 1 --mediation --timing --trace-log #2245 usingtechnology</li> <li>Fix formatting and grammatical errors in different readme's #2222 ff137</li> <li>Fix broken link in README #2221 ff137</li> <li>fix: run only on main, forks ok #2166 anwalker293</li> <li>Update Alice Wants a JSON-LD Credential to fix invocation #2219 swcurran</li> <li>Dependencies and Internal Updates</li> <li>Bump requests from 2.30.0 to 2.31.0 in /demo/playground/scripts dependenciesPull requests that update a dependency file #2238 dependabot bot</li> <li>Upgrade codegen tools in scripts/generate-open-api-spec and publish Swagger 2.0 and OpenAPI 3.0 specs #2246 ff137</li> <li>ACA-Py Administrative Updates</li> <li>Propose adding Jason Sherman usingtechnology as a Maintainer #2263 swcurran</li> <li>Updating Maintainers list to be accurate and using the TOC format #2258 swcurran</li> <li>Message Tracing/Timing Updates</li> <li>Add updated ELK stack for demos. #2236 usingtechnology</li> <li>Release management pull requests</li> <li>0.8.2 #2285 swcurran</li> <li>0.8.2-rc2 #2284 swcurran</li> <li>0.8.2-rc1 #2282 swcurran</li> <li>0.8.2-rc0 #2260 swcurran</li> </ul>"},{"location":"CHANGELOG/#081","title":"0.8.1","text":""},{"location":"CHANGELOG/#april-5-2023","title":"April 5, 2023","text":"<p>Version 0.8.1 is an urgent update to Release 0.8.0 to address an inability to execute the <code>upgrade</code> command. The <code>upgrade</code> command is needed for 0.8.0 Pull Request [#2116] - \"UPGRADE: Fix multi-use invitation performance\", which is useful for (at least) deployments of ACA-Py as a mediator. In the release, the upgrade process is revamped, and documented in Upgrading ACA-Py.</p> <p>Key points about upgrading for those with production, pre-0.8.1 ACA-Py deployments:</p> <ul> <li>Upgrades now happen automatically on startup, when needed.</li> <li>The version of the last executed upgrade, even if it is a \"no change\" upgrade,   is put into secure storage and is used to detect when future upgrades are needed.</li> <li>Upgrades are needed when the running version is greater than the version is     secure storage.</li> <li>If you have an existing, pre-0.8.1 deployment with many connection records, there may be a delay in starting as an upgrade will be run that loads and saves every connection record, updating the data in the record in the process.</li> <li>A mechanism is to be added (see Issue #2201) for preventing an upgrade   running if it should not be run automatically, and requires using the   <code>upgrade</code> command. To date, there has been no need for this feature.</li> <li>See the Upgrading ACA-Py document for more details.</li> </ul>"},{"location":"CHANGELOG/#postgres-support-with-aries-askar","title":"Postgres Support with Aries Askar","text":"<p>Recent changes to Aries Askar have resulted in Askar supporting Postgres version 11 and greater. If you are on Postgres 10 or earlier and want to upgrade to use Askar, you must migrate your database to Postgres 10.</p> <p>We have also noted that in some container orchestration environments such as Red Hat's OpenShift and possibly other Kubernetes distributions, Askar using Postgres versions greater than 14 do not install correctly. Please monitor [Issue #2199] for an update to this limitation. We have found that Postgres 15 does install correctly in other environments (such as in <code>docker compose</code> setups).</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_2","title":"Categorized List of Pull Requests","text":"<ul> <li>Fixes for the <code>upgrade</code> Command</li> <li>Change upgrade definition file entry from 0.8.0 to 0.8.1 #2203 swcurran</li> <li>Add Upgrading ACA-Py document #2200 swcurran</li> <li>Fix: Indy WalletAlreadyOpenedError during upgrade process #2196 shaangill025</li> <li>Fix: Resolve Upgrade Config file in Container #2193 shaangill025</li> <li>Update and automate ACA-Py upgrade process #2185 shaangill025</li> <li>Adds the upgrade command YML file to the PyPi Release #2179 swcurran</li> <li>Test and Documentation</li> <li>3.7 and 3.10 unittests fix #2187 Jsyro</li> <li>Doc update and some test scripts #2189 ianco</li> <li>Create UnitTests.md #2183 swcurran</li> <li>Add link to recorded session about the ACA-Py Integration tests #2184 swcurran</li> <li>Release management pull requests</li> <li>0.8.1 #2207 swcurran</li> <li>0.8.1-rc2 #2198 swcurran</li> <li>0.8.1-rc1 #2194 swcurran</li> <li>0.8.1-rc0 #2190 swcurran</li> </ul>"},{"location":"CHANGELOG/#080","title":"0.8.0","text":""},{"location":"CHANGELOG/#march-14-2023","title":"March 14, 2023","text":"<p>0.8.0 is a breaking change that contains all updates since release 0.7.5. It extends the previously tagged <code>1.0.0-rc1</code> release because it is not clear when the 1.0.0 release will be finalized. Many of the PRs in this release were previously included in the <code>1.0.0-rc1</code> release. The categorized list of PRs separates those that are new from those in the <code>1.0.0-rc1</code> release candidate.</p> <p>There are not a lot of new Aries Framework features in this release, as the focus has been on cleanup and optimization. The biggest addition is the inclusion with ACA-Py of a universal resolver interface, allowing an instance to have both local resolvers for some DID Methods and a call out to an external universal resolver for other DID Methods. Another significant new capability is full support for Hyperledger Indy transaction endorsement for Authors and Endorsers. A new repo aries-endorser-service has been created that is a pre-configured instance of ACA-Py for use as an Endorser service.</p> <p>A recently completed feature that is outside of ACA-Py is a script to migrate existing ACA-Py storage from Indy SDK format to Aries Askar format. This enables existing deployments to switch to using the newer Aries Askar components. For details see the converter in the aries-acapy-tools repository.</p>"},{"location":"CHANGELOG/#container-publishing-updated","title":"Container Publishing Updated","text":"<p>With this release, a new automated process publishes container images in the Hyperledger container image repository. New images for the release are automatically published by the GitHubAction Workflows: publish.yml and publish-indy.yml. The actions are triggered when a release is tagged, so no manual action is needed. The images are published in the Hyperledger Package Repository under aries-cloudagent-python and a link to the packages added to the repositories main page (under \"Packages\"). Additional information about the container image publication process can be found in the document Container Images and Github Actions.</p> <p>The ACA-Py container images are based on Python 3.6 and 3.9 <code>slim-bullseye</code> images, and are designed to support <code>linux/386 (x86)</code>, <code>linux/amd64 (x64)</code>, and <code>linux/arm64</code>. However, for this release, the publication of multi-architecture containers is disabled. We are working to enable that through the updating of some dependencies that lack that capability. There are two flavors of image built for each Python version. One contains only the Indy/Aries Shared Libraries only (Aries Askar, Indy VDR and Indy Shared RS, supporting only the use of <code>--wallet-type askar</code>). The other (labelled <code>indy</code>) contains the Indy/Aries shared libraries and the Indy SDK (considered deprecated). For new deployments, we recommend using the Python 3.9 Shared Library images. For existing deployments, we recommend migrating to those images.</p> <p>Those currently using the container images published by BC Gov on Docker Hub should change to use those published to the Hyperledger Package Repository under aries-cloudagent-python.</p>"},{"location":"CHANGELOG/#breaking-changes-and-upgrades","title":"Breaking Changes and Upgrades","text":""},{"location":"CHANGELOG/#pr-2034-implicit-connections","title":"PR #2034 -- Implicit connections","text":"<p>The break impacts existing deployments that support implicit connections, those initiated by another agent using a Public DID for this instance instead of an explicit invitation. Such deployments need to add the configuration parameter <code>--requests-through-public-did</code> to continue to support that feature. The use case is that an ACA-Py instance publishes a public DID on a ledger with a DIDComm <code>service</code> in the DIDDoc. Other agents resolve that DID, and attempt to establish a connection with the ACA-Py instance using the <code>service</code> endpoint. This is called an \"implicit\" connection in RFC 0023 DID Exchange.</p>"},{"location":"CHANGELOG/#pr-1913-unrevealed-attributes-in-presentations","title":"PR #1913 -- Unrevealed attributes in presentations","text":"<p>Updates the handling of \"unrevealed attributes\" during verification of AnonCreds presentations, allowing them to be used in a presentation, with additional data that can be checked if for unrevealed attributes. As few implementations of Aries wallets support unrevealed attributes in an AnonCreds presentation, this is unlikely to impact any deployments.</p>"},{"location":"CHANGELOG/#pr-2145-update-webhook-message-to-terse-form-by-default-added-startup-flag-debug-webhooks-for-full-form","title":"PR #2145 - Update webhook message to terse form by default, added startup flag --debug-webhooks for full form","text":"<p>The default behavior in ACA-Py has been to keep the full text of all messages in the protocol state object, and include the full protocol state object in the webhooks sent to the controller. When the messages include an object that is very large in all the messages, the webhook may become too big to be passed via HTTP. For example, issuing a credential with a photo as one of the claims may result in a number of copies of the photo in the protocol state object and hence, very large webhooks. This change reduces the size of the webhook message by eliminating redundant data in the protocol state of the \"Issue Credential\" message as the default, and adds a new parameter to use the old behavior.</p>"},{"location":"CHANGELOG/#upgrade-pr-2116-upgrade-fix-multi-use-invitation-performance","title":"UPGRADE PR #2116 - UPGRADE: Fix multi-use invitation performance","text":"<p>The way that multiuse invitations in previous versions of ACA-Py caused performance to degrade over time. An update was made to add state into the tag names that eliminated the need to scan the tags when querying storage for the invitation.</p> <p>If you are using multiuse invitations in your existing (pre-<code>0.8.0</code> deployment of ACA-Py, you can run an <code>upgrade</code> to apply this change. To run upgrade from previous versions, use the following command using the <code>0.8.0</code> version of ACA-Py, adding you wallet settings:</p> <p><code>aca-py upgrade &lt;other wallet config settings&gt; --from-version=v0.7.5 --upgrade-config-path ./upgrade.yml</code></p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_3","title":"Categorized List of Pull Requests","text":"<ul> <li>Verifiable credential, presentation and revocation handling updates</li> <li>BREAKING: Update webhook message to terse form [default, added startup flag --debug-webhooks for full form #2145 by victorlee0505</li> <li>Add startup flag --light-weight-webhook to trim down outbound webhook payload #1941 victorlee0505</li> <li>feat: add verification method issue-credentials-2.0/send endpoint #2135 chumbert</li> <li>Respect auto-verify-presentation flag in present proof v1 and v2 #2097 dbluhm</li> <li>Feature: enabled handling VPs (request, creation, verification) with different VCs #1956 (teanas)</li> <li>fix: update issue-credential endpoint summaries #1997 (PeterStrob)</li> <li>fix claim format designation in presentation submission #2013 (rmnre)</li> <li>#2041 - Issue JSON-LD has invalid Admin API documentation #2046 (jfblier-amplitude)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Refactor ledger correction code and insert into revocation error handling #1892 (ianco)</li> <li>Indy ledger fixes and cleanups #1870 (andrewwhitehead)</li> <li>Refactoring of revocation registry creation #1813 (andrewwhitehead)</li> <li>Fix: \bthe type of tails file path to string. #1925 (baegjae)</li> <li>Pre-populate revoc_reg_id on IssuerRevRegRecord #1924 (andrewwhitehead)</li> <li>Leave credentialStatus element in the LD credential #1921 (tsabolov)</li> <li>BREAKING: Remove aca-py check for unrevealed revealed attrs on proof validation #1913 (ianco)</li> <li>Send webhooks upon record/credential deletion #1906 (frostyfrog)</li> </ul> </li> <li> <p>Out of Band (OOB) and DID Exchange / Connection Handling / Mediator</p> </li> <li>UPGRADE: Fix multi-use invitation performance #2116 reflectivedevelopment</li> <li>fix: public did mediator routing keys as did keys #1977 (dbluhm)</li> <li>Fix for mediator load testing race condition when scaling horizontally #2009 (ianco)</li> <li>BREAKING: Allow multi-use public invites and public invites with metadata #2034 (mepeltier)</li> <li>Do not reject OOB invitation with unknown handshake protocol\\(s\\) #2060 (andrewwhitehead)</li> <li>fix: fix connection timing bug #2099 (reflectivedevelopment)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fix: <code>--mediator-invitation</code> with OOB invitation + cleanup  #1970 (shaangill025)</li> <li>include image_url in oob invitation #1966 (Zzocker)</li> <li>feat: 00B v1.1 support #1962 (shaangill025)</li> <li>Fix: OOB - Handling of minor versions #1940 (shaangill025)</li> <li>fix: failed connectionless proof request on some case #1933 (kukgini)</li> <li>fix: propagate endpoint from mediation record #1922 (cjhowland)</li> <li>Feat/public did endpoints for agents behind mediators #1899 (cjhowland)</li> </ul> </li> <li> <p>DID Registration and Resolution related updates</p> </li> <li>feat: allow marking non-SOV DIDs as public #2144 chumbert</li> <li>fix: askar exception message always displaying null DID #2155 chumbert</li> <li>feat: enable creation of DIDs for all registered methods #2067 (chumbert)</li> <li>fix: create local DID return schema #2086 (chumbert)</li> <li>feat: universal resolver - configurable authentication #2095 (chumbert)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>feat: add universal resolver #1866 (dbluhm)</li> <li>fix: resolve dids following new endpoint rules #1863 (dbluhm)</li> <li>fix: didx request cannot be accepted #1881 (rmnre)</li> <li>did method &amp; key type registry #1986 (burdettadam)</li> <li>Fix/endpoint attrib structure #1934 (cjhowland)</li> <li>Simple did registry #1920 (burdettadam)</li> <li>Use did:key for recipient keys #1886 (frostyfrog)</li> </ul> </li> <li> <p>Hyperledger Indy Endorser/Author Transaction Handling</p> </li> <li>Update some of the demo Readme and Endorser instructions #2122 swcurran</li> <li>Special handling for the write ledger #2030 (ianco)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fix/txn job setting #1994 (ianco)</li> <li>chore: fix ACAPY_PROMOTE-AUTHOR-DID flag  #1978 (morrieinmaas)</li> <li>Endorser write DID transaction #1938 (ianco)</li> <li>Endorser doc updates and some bug fixes #1926 (ianco)</li> </ul> </li> <li> <p>Admin API Additions</p> </li> <li>fix: response type on delete-tails-files endpoint #2133 chumbert</li> <li>OpenAPI validation fixes #2127 loneil</li> <li> <p>Delete tail files #2103 ramreddychalla94</p> </li> <li> <p>Startup Command Line / Environment / YAML Parameter Updates</p> </li> <li>Update webhook message to terse form [default, added startup flag --debug-webhooks for full form #2145 by victorlee0505</li> <li>Add startup flag --light-weight-webhook to trim down outbound webhook payload #1941 victorlee0505</li> <li>Add missing --mediator-connections-invite cmd arg info to docs #2051 (matrixik)</li> <li>Issue #2068 boolean flag change to support HEAD requests to default route #2077 (johnekent)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Add seed command line parameter but use only if also an \"allow insecure seed\" parameter is set #1714 (DaevMithran)</li> </ul> </li> <li> <p>Internal Aries framework data handling updates</p> </li> <li>fix: resolver api schema inconsistency #2112 (TimoGlastra)</li> <li>fix: return if return route but no response #1853 (TimoGlastra)</li> <li>Multi-ledger/Multi-tenant issues #2022 (ianco)</li> <li>fix: Correct typo in model -- required spelled incorrectly #2031 (swcurran)</li> <li>Code formatting #2053 (ianco)</li> <li>Improved validation of record state attributes #2071 (rmnre)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>fix: update RouteManager methods use to pass profile as parameter #1902 (chumbert)</li> <li>Allow fully qualified class names for profile managers #1880 (chumbert)</li> <li>fix: unable to use askar with in memory db #1878 (dbluhm)</li> <li>Enable manually triggering keylist updates during connection #1851 (dbluhm)</li> <li>feat: make base wallet route access configurable #1836 (dbluhm)</li> <li>feat: event and webhook on keylist update stored #1769 (dbluhm)</li> <li>fix: Safely shutdown when root_profile uninitialized #1960 (frostyfrog)</li> <li>feat: include connection ids in keylist update webhook #1914 (dbluhm)</li> <li>fix: incorrect response schema for discover features #1912 (dbluhm)</li> <li>Fix: SchemasInputDescriptorFilter: broken deserialization renders generated clients unusable #1894 (rmnre)</li> <li>fix: schema class can set Meta.unknown #1885 (dbluhm)</li> </ul> </li> <li> <p>Unit, Integration, and Aries Agent Test Harness Test updates</p> </li> <li>Additional integration tests for revocation scenarios #2055 (ianco)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fixes a few AATH failures #1897 (ianco)</li> <li>fix: warnings in tests from IndySdkProfile #1865 (dbluhm)</li> <li>Unit test fixes for python 3.9 #1858 (andrewwhitehead)</li> <li>Update pip-audit.yml #1945 (ryjones)</li> <li>Update pip-audit.yml #1944 (ryjones)</li> </ul> </li> <li> <p>Dependency, Python version, GitHub Actions and Container Image Changes</p> </li> <li>Remove CircleCI Status since we aren't using CircleCI anymore #2163 swcurran</li> <li>Update ACA-Py docker files to produce OpenShift compatible images #2130 WadeBarnes</li> <li>Temporarily disable multi-architecture image builds #2125 WadeBarnes</li> <li>Fix ACA-py image builds #2123 WadeBarnes</li> <li>Fix publish workflows #2117 WadeBarnes</li> <li>fix: indy dependency version format #2054 (chumbert)</li> <li>ci: add gha for pr-tests #2058 (dbluhm)</li> <li>ci: test additional versions of python nightly #2059 (dbluhm)</li> <li>Update github actions dependencies \\(for node16 support\\) #2066 (andrewwhitehead)</li> <li>Docker images and GHA for publishing images #2076 (dbluhm)</li> <li>Update dockerfiles to use python 3.9 #2109 (ianco)</li> <li>Updating base images from slim-buster to slim-bullseye #2105 (pradeepp88)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>feat: update pynacl version from 1.4.0 to 1.50 #1981 (morrieinmaas)</li> <li>Fix: web.py dependency - integration tests &amp; demos #1973 (shaangill025)</li> <li>chore: update pydid #1915 (dbluhm)</li> </ul> </li> <li> <p>Demo and Documentation Updates</p> </li> <li>[fix] Removes extra comma that prevents swagger from accepting the presentation request #2149 swcurran</li> <li>Initial plugin docs #2138 ianco</li> <li>Acme workshop #2137 ianco</li> <li>Fix: Performance Demo [no --revocation] #2151 shaangill025</li> <li>Fix typos in alice-local.sh &amp; faber-local.sh #2010 (naonishijima)</li> <li>Added a bit about manually creating a revoc reg tails file #2012 (ianco)</li> <li>Add ability to set docker container name #2024 (matrixik)</li> <li>Doc updates for json demo #2026 (ianco)</li> <li>Multitenancy demo \\(docker-compose with postgres and ngrok\\) #2089 (ianco)</li> <li>Allow using YAML configuration file with run_docker #2091 (matrixik)</li> <li> <p>Previously flagged in release 1.0.0-rc1</p> <ul> <li>Fixes to acme exercise code #1990 (ianco)</li> <li>Fixed bug in run_demo script #1982 (pasquale95)</li> <li>Transaction Author with Endorser demo #1975 (ianco)</li> <li>Redis Plugins [redis_cache &amp; redis_queue] related updates #1937 (shaangill025)</li> </ul> </li> <li> <p>Release management pull requests</p> </li> <li>0.8.0 release #2169 (swcurran)</li> <li>0.8.0-rc0 release updates #2115 (swcurran)</li> <li>Previously flagged in release 1.0.0-rc1<ul> <li>Release 1.0.0-rc0 #1904 (swcurran)</li> <li>Add 0.7.5 patch Changelog entry to main branch Changelog #1996 (swcurran)</li> <li>Release 1.0.0-rc1 #2005 (swcurran)</li> </ul> </li> </ul>"},{"location":"CHANGELOG/#075","title":"0.7.5","text":""},{"location":"CHANGELOG/#october-26-2022","title":"October 26, 2022","text":"<p>0.7.5 is a patch release to deal primarily to add PR #1881 DID Exchange in ACA-Py 0.7.4 with explicit invitations and without auto-accept broken. A couple of other PRs were added to the release, as listed below, and in Milestone 0.7.5.</p>"},{"location":"CHANGELOG/#list-of-pull-requests","title":"List of Pull Requests","text":"<ul> <li>Changelog and version updates for version 0.7.5-rc1 #1985 (swcurran)</li> <li>Endorser doc updates and some bug fixes #1926 (ianco)</li> <li>Fix: web.py dependency - integration tests &amp; demos #1973 (shaangill025)</li> <li>Endorser write DID transaction #1938 (ianco)</li> <li>fix: didx request cannot be accepted #1881 (rmnre)</li> <li>Fix: OOB - Handling of minor versions #1940 (shaangill025)</li> <li>fix: Safely shutdown when root_profile uninitialized #1960 (frostyfrog)</li> <li>feat: 00B v1.1 support #1962 (shaangill025)</li> <li>0.7.5 Cherry Picks #1967 (frostyfrog)</li> <li>Changelog and version updates for version 0.7.5-rc0 #1969 (swcurran)</li> <li>Final 0.7.5 changes #1991 (swcurran)</li> </ul>"},{"location":"CHANGELOG/#074","title":"0.7.4","text":""},{"location":"CHANGELOG/#june-30-2022","title":"June 30, 2022","text":"<p> Existing multitenant JWTs invalidated when a new JWT is generated: If you have a pre-existing implementation with existing Admin API authorization JWTs, invoking the endpoint to get a JWT now invalidates the existing JWT. Previously an identical JWT would be created. Please see this comment on PR #1725 for more details.</p> <p>0.7.4 is a significant release focused on stability and production deployments. As the \"patch\" release number indicates, there were no breaking changes in the Admin API, but a huge volume of updates and improvements.  Highlights of this release include:</p> <ul> <li>A major performance and stability improvement resulting from the now recommended use of Aries Askar instead of the Indy-SDK.</li> <li>There are significant improvements and tools for dealing with revocation-related issues.</li> <li>A lot of work has been on the handling of Hyperledger Indy transaction endorsements.</li> <li>ACA-Py now has a pluggable persistent queues mechanism in place, with Redis and Kafka support available (albeit with work still to come on documentation).</li> </ul> <p>In addition, there are a significant number of general enhancements, bug fixes, documentation updates and code management improvements.</p> <p>This release is a reflection of the many groups stressing ACA-Py in production environments, reporting issues and the resulting solutions. We also have a very large number of contributors to ACA-Py, with this release having PRs from 22 different individuals. A big thank you to all of those using ACA-Py, raising issues and providing solutions.</p>"},{"location":"CHANGELOG/#major-enhancements","title":"Major Enhancements","text":"<p>A lot of work has been put into this release related to performance and load testing, with significant updates being made to the key \"shared component\" ACA-Py dependencies (Aries Askar, Indy VDR) and Indy Shared RS (including CredX). We now recommend using those components (by using <code>--wallet-type askar</code> in the ACA-Py startup parameters) for new ACA-Py deployments. A wallet migration tool from indy-sdk storage to Askar storage is still needed before migrating existing deployment to Askar. A big thanks to those creating/reporting on stress test scenarios, and especially the team at LISSI for creating the aries-cloudagent-loadgenerator to make load testing so easy! And of course to the core ACA-Py team for addressing the findings.</p> <p>The largest enhancement is in the area of the endorsing of Hyperledger Indy ledger transactions, enabling an instance of ACA-Py to act as an Endorser for Indy authors needing endorsements to write objects to an Indy ledger. We're working on an Aries Endorser Service based on the new capabilities in ACA-Py, an Endorser to be easily operated by an organization, ideally with a controller starter kit supporting a basic human and automated approvals business workflow. Contributions welcome!</p> <p>A focus towards the end of the 0.7.4 development and release cycle was on the handling of AnonCreds revocation in ACA-Py. Most important, a production issue was uncovered where by an ACA-Py issuer's local Revocation Registry data could get out of sync with what was published on an Indy ledger, resulting in an inability to publish new RevRegEntry transactions -- making new revocations impossible. As a result, we have added some new endpoints to enable an update to the RevReg storage such that RevRegEntry transactions can again be published to the ledger. Other changes were added related to revocation in general and in the handling of tails files in particular.</p> <p>The team has worked a lot on evolving the persistent queue (PQ) approach available in ACA-Py. We have landed on a design for the queues for inbound and outbound messages using a default in-memory implementation, and the ability to replace the default method with implementations created via an ACA-Py plugin. There are two concrete, out-of-the-box external persistent queuing solutions available for Redis and Kafka. Those ACA-Py persistent queue implementation repositories will soon be migrated to the Aries project within the Hyperledger Foundation's GitHub organization. Anyone else can implement their own queuing plugin as long as it uses the same interface.</p> <p>Several new ways to control ACA-Py configurations were added, including new startup parameters, Admin API parameters to control instances of protocols, and additional web hook notifications.</p> <p>A number of fixes were made to the Credential Exchange protocols, both for V1 and V2, and for both AnonCreds and W3C format VCs. Nothing new was added and there no changes in the APIs.</p> <p>As well there were a number of internal fixes, dependency updates, documentation and demo changes, developer tools and release management updates. All the usual stuff needed for a healthy, growing codebase.</p>"},{"location":"CHANGELOG/#categorized-list-of-pull-requests_4","title":"Categorized List of Pull Requests","text":"<ul> <li>Hyperledger Indy Endorser related updates:</li> <li>Fix order of operations connecting faber to endorser #1716 (ianco)</li> <li>Endorser support for updating DID endpoints on ledger #1696 (frostyfrog)</li> <li>Add \"sent\" key to both Schema and Cred Defs when using Endorsers #1663 (frostyfrog)</li> <li>Add cred_def_id to metadata when using an Endorser #1655 (frostyfrog)</li> <li>Update Endorser documentation #1646 (chumbert)</li> <li>Auto-promote author did to public after endorsing #1607 (ianco)</li> <li>DID updates for endorser #1601 (ianco)</li> <li>Qualify did exch connection lookup by role #1670 (ianco)</li> <li> <p>Use provided connection_id if provided #1726 (ianco)</p> </li> <li> <p>Additions to the startup parameters, Admin API and Web Hooks</p> </li> <li>Improve typing of settings and add plugin settings object #1833 (dbluhm)</li> <li>feat: accept taa using startup parameter --accept-taa #1643 (TimoGlastra)</li> <li>Add auto_verify flag in present-proof protocol #1702 (DaevMithran)</li> <li>feat: query connections by their_public_did #1637 (TimoGlastra)</li> <li>feat: enable webhook events for mediation records #1614 (TimoGlastra)</li> <li>Feature/undelivered events #1694 (mepeltier)</li> <li>Allow use of SEED when creating local wallet DID Issue-1682 Issue-1682 #1705 (DaevMithran)</li> <li>Feature: Add the ability to deny specific plugins from loading #1737 (frostyfrog)</li> <li>feat: Add filter param to connection list for invitations #1797 (frostyfrog)</li> <li> <p>Fix missing webhook handler #1816 (ianco)</p> </li> <li> <p>Persistent Queues</p> </li> <li> <p>Redis PQ Cleanup in preparation for enabling the uses of plugin PQ implementations [Issue#1659] #1659 (shaangill025)</p> </li> <li> <p>Credential Revocation and Tails File Handling</p> </li> <li>Fix handling of non-revocable credential when timestamp is specified \\(askar/credx\\) #1847 (andrewwhitehead)</li> <li>Additional endpoints to get revocation details and fix \"published\" status #1783 (ianco)</li> <li>Fix IssuerCredRevRecord state update on revocation publish #1827 (andrewwhitehead)</li> <li>Fix put_file when the server returns a redirect #1808 (andrewwhitehead)</li> <li>Adjust revocation registry update procedure to shorten transactions #1804 (andrewwhitehead)</li> <li>fix: Resolve Revocation Notification environment variable name collision #1751 (frostyfrog)</li> <li>fix: always notify if revocation notification record exists #1665 (TimoGlastra)</li> <li>Fix for AnonCreds non-revoc proof with no timestamp #1628 (ianco)</li> <li>Fixes for v7.3.0 - Issue #1597 #1711 (shaangill025)<ul> <li>Fixes Issue 1 from #1597: Tails file upload fails when a credDef is created and multi ledger support is enabled</li> </ul> </li> <li>Fix tails server upload multi-ledger mode #1785 (ianco)</li> <li> <p>Feat/revocation notification v2 #1734 (frostyfrog)</p> </li> <li> <p>Issue Credential, Present Proof updates/fixes</p> </li> <li>Fix: Present Proof v2 - check_proof_vs_proposal update to support proof request with restrictions #1820 (shaangill025)</li> <li>Fix: present-proof v1 send-proposal flow #1811 (shaangill025)</li> <li>Prover - verification outcome from presentation ack message #1757 (shaangill025)</li> <li>feat: support connectionless exchange #1710 (TimoGlastra)</li> <li>Fix: DIF proof proposal when creating bound presentation request [Issue#1687] #1690 (shaangill025)</li> <li>Fix DIF PresExch and OOB request_attach delete unused connection #1676 (shaangill025)</li> <li>Fix DIFPresFormatHandler returning invalid V20PresExRecord on presentation verification #1645 (rmnre)</li> <li>Update aries-askar patch version to at least 0.2.4 as 0.2.3 does not include backward compatibility #1603 (acuderman)</li> <li>Fixes for credential details in issue-credential webhook responses #1668 (andrewwhitehead)</li> <li>Fix: present-proof v2 send-proposal issue#1474 #1667 (shaangill025)<ul> <li>Fixes Issue 3b from #1597: V2 Credential exchange ignores the auto-respond-credential-request</li> </ul> </li> <li>Revert change to send_credential_ack return value #1660 (andrewwhitehead)</li> <li>Fix usage of send_credential_ack #1653 (andrewwhitehead)</li> <li>Replace blank credential/presentation exchange states with abandoned state #1605 (andrewwhitehead)<ul> <li>Fixes Issue 4 from #1597: Wallet type askar has issues when receiving V1 credentials</li> </ul> </li> <li>Fixes and cleanups for issue-credential 1.0 #1619 (andrewwhitehead)</li> <li> <p>Fix: Duplicated schema and cred_def - Askar and Postgres #1800 (shaangill025)</p> </li> <li> <p>Mediator updates and fixes</p> </li> <li>feat: allow querying default mediator from base wallet #1729 (dbluhm)</li> <li> <p>Added async with for mediator record delete #1749 (dejsenlitro)</p> </li> <li> <p>Multitenacy updates and fixes</p> </li> <li>feat: create new JWT tokens and invalidate older for multitenancy #1725 (TimoGlastra)</li> <li> <p>Multi-tenancy stale wallet clean up #1692 (dbluhm)</p> </li> <li> <p>Dependencies and internal code updates/fixes</p> </li> <li>Update pyjwt to 2.4 #1829 (andrewwhitehead)</li> <li>Fix external Outbound Transport loading code #1812 (frostyfrog)</li> <li>Fix iteration over key list, update Askar to 0.2.5 #1740 (andrewwhitehead)</li> <li>Fix: update IndyLedgerRequestsExecutor logic - multitenancy and basic base wallet type  #1700 (shaangill025)</li> <li>Move database operations inside the session context #1633 (acuderman)</li> <li>Upgrade ConfigArgParse to version 1.5.3 #1627 (WadeBarnes)</li> <li>Update aiohttp dependency #1606 (acuderman)</li> <li>did-exchange implicit request pthid update &amp; invitation key verification #1599 (shaangill025)</li> <li>Fix auto connection response not being properly mediated #1638 (dbluhm)</li> <li>platform target in run tests. #1697 (burdettadam)</li> <li>Add an integration test for mixed proof with a revocable cred and a n\u2026 #1672 (ianco)</li> <li>Fix: Inbound Transport is_external attribute #1802 (shaangill025)</li> <li>fix: add a close statement to ensure session is closed on error #1777 (reflectivedevelopment)</li> <li>Adds <code>transport_id</code> variable assignment back to outbound enqueue method #1776 (amanji)</li> <li> <p>Replace async workaround within document loader #1774 (frostyfrog)</p> </li> <li> <p>Documentation and Demo Updates</p> </li> <li>Use default wallet type askar for alice/faber demo and bdd tests #1761 (ianco)</li> <li>Update the Supported RFCs document for 0.7.4 release #1846 (swcurran)</li> <li>Fix a typo in DevReadMe.md #1844 (feknall)</li> <li>Add troubleshooting document, include initial examples - ledger connection, out-of-sync RevReg #1818 (swcurran)</li> <li>Update POST /present-proof/send-request to POST /present-proof-2.0/send-request #1824 (lineko)</li> <li>Fetch from --genesis-url likely to fail in composed container #1746 (tdiesler)</li> <li>Fixes logic for web hook formatter in Faber demo #1739 (amanji)</li> <li>Multitenancy Docs Update #1706 (MonolithicMonk)</li> <li>#1674 Add basic DOCKER_ENV logging for run_demo #1675 (tdiesler)</li> <li>Performance demo updates #1647 (ianco)</li> <li>docs: supported features attribution #1654 (TimoGlastra)</li> <li>Documentation on existing language wrappers for aca-py #1738 (etschelp)</li> <li> <p>Document impact of multi-ledger on TAA acceptance #1778 (ianco)</p> </li> <li> <p>Code management and contributor/developer support updates</p> </li> <li>Set prefix for integration test demo agents; some code cleanup #1840 (andrewwhitehead)</li> <li>Pin markupsafe at version 2.0.1 #1642 (andrewwhitehead)</li> <li>style: format with stable black release #1615 (TimoGlastra)</li> <li>Remove references to play with von #1688 (ianco)</li> <li>Add pre-commit as optional developer tool #1671 (dbluhm)</li> <li>run_docker start - pass environment variables #1715 (shaangill025)</li> <li>Use local deps only #1834 (ryjones)</li> <li>Enable pip-audit #1831 (ryjones)</li> <li> <p>Only run pip-audit on main repo #1845 (ryjones)</p> </li> <li> <p>Release management pull requests</p> </li> <li>0.7.4 Release Changelog and version update #1849 (swcurran)</li> <li>0.7.4-rc5 changelog, version and ReadTheDocs updates #1838 (swcurran)</li> <li>Update changelog and version for 0.7.4-rc4 #1830 (swcurran)</li> <li>Changelog, version and ReadTheDocs updates for 0.7.4-rc3 release #1817 (swcurran)</li> <li>0.7.4-rc2 update #1771 (swcurran)</li> <li>Some ReadTheDocs File updates #1770 (swcurran)</li> <li>0.7.4-RC1 Changelog intro paragraph - fix copy/paste error #1753 (swcurran)</li> <li>Fixing the intro paragraph and heading in the changelog of this 0.7.4RC1 #1752 (swcurran)</li> <li>Updates to Changelog for 0.7.4. RC1 release #1747 (swcurran)</li> <li>Prep for adding the 0.7.4-rc0 tag #1722 (swcurran)</li> <li>Added missed new module -- upgrade -- to the RTD generated docs #1593 (swcurran)</li> <li>Doh....update the date in the Changelog for 0.7.3 #1592 (swcurran)</li> </ul>"},{"location":"CHANGELOG/#073","title":"0.7.3","text":""},{"location":"CHANGELOG/#january-10-2022","title":"January 10, 2022","text":"<p>This release includes some new AIP 2.0 features out (Revocation Notification and Discover Features 2.0), a major new feature for those using Indy ledger (multi-ledger support), a new \"version upgrade\" process that automates updating data in secure storage required after a new release, and a fix for a critical bug in some mediator scenarios. The release also includes several new pieces of documentation (upgrade processing, storage database information and logging) and some other documentation updates that make the ACA-Py Read The Docs site useful again. And of course, some recent bug fixes and cleanups are included.</p> <p>There is a BREAKING CHANGE for those deploying ACA-Py with an external outbound queue implementation (see PR #1501). As far as we know, there is only one organization that has such an implementation and they were involved in the creation of this PR, so we are not making this release a minor or major update. However, anyone else using an external queue should be aware of the impact of this PR that is included in the release.</p> <p>For those that have an existing deployment of ACA-Py with long-lasting connection records, an upgrade is needed to use RFC 434 Out of Band and the \"reuse connection\" as the invitee. In PR #1453 (details below) a performance improvement was made when finding a connection for reuse. The new approach (adding a tag to the connection to enable searching) applies only to connections made using this ACA-Py release and later, and \"as-is\" connections made using earlier releases of ACA-Py will not be found as reuse candidates. A new \"Upgrade deployment\" capability (#1557, described below) must be executed to update your deployment to add tags for all existing connections.</p> <p>The Supported RFCs document has been updated to reflect the addition of the AIP 2.0 RFCs for which support was added.</p> <p>The following is an annotated list of PRs in the release, including a link to each PR.</p> <ul> <li>AIP 2.0 Features</li> <li>Discover Features Protocol: v1_0 refactoring and v2_0 implementation #1500<ul> <li>Updates the Discover Features 1.0 (AIP 1.0) implementation and implements the new 2.0 version. In doing so, adds generalized support for goal codes to ACA-Py.</li> <li>fix DiscoveryExchangeRecord RECORD_TOPIC typo fix #1566</li> </ul> </li> <li>Implement Revocation Notification v1.0 #1464</li> <li>Fix integration tests (revocation notifications) #1528</li> <li>Add Revocation notification support to alice/faber #1527</li> <li>Other New Features</li> <li>Multiple Indy Ledger support and State Proof verification #1425<ul> <li>Remove required dependencies from multi-ledger code that was requiring the import of Aries Askar even when not being used#1550</li> <li>Fixed IndyDID resolver bug after Tag 0.7.3rc0 created #1569</li> <li>Typo vdr service name #1563</li> <li>Fixes and cleanup for multiple ledger support with Askar #1583</li> </ul> </li> <li>Outbound Queue - more usability improvements #1501</li> <li>Display QR code when generating/displaying invites on startup #1526</li> <li>Enable WS Pings for WS Inbound Transport #1530<ul> <li>Faster detection of lost Web Socket connections; implementation verified with an existing mediator.</li> </ul> </li> <li>Performance Improvement when using connection reuse in OOB and there are many DID connections. ConnRecord tags - their_public_did and invitation_msg_id #1543<ul> <li>In previous releases, a \"their_public_did\" was not a tag, so to see if you can reuse a connection, all connections were retrieved from the database to see if a matching public DID can be found. Now, connections created after deploying this release will have a tag on the connection such that an indexed query can be used. See \"Breaking Change\" note above and \"Update\" feature below.</li> <li>Follow up to #1543 - Adding invitation_msg_id and their_public_did back to record_value #1553</li> </ul> </li> <li>A generic \"Upgrade Deployment\" capability was added to ACA-Py that operates like a database migration capability in relational databases. When executed (via a command line option), a current version of the deployment is detected and if any storage updates need be applied to be consistent with the new version, they are, and the stored \"current version\"is updated to the new version. An instance of this capability can be used to address the new feature #1543 documented above. #1557</li> <li>Adds a \"credential_revoked\" state to the Issue Credential protocol state object. When the protocol state object is retained past the completion of the protocol, it is updated when the credential is revoked. #1545</li> <li>Updated a missing dependency that recently caused an error when using the <code>--version</code> command line option #1589</li> <li>Critical Fixes</li> <li>Fix connection record response for mobile #1469</li> <li>Documentation Additions and Updates</li> <li>added documentation for wallet storage databases #1523</li> <li>added logging documentation #1519</li> <li>Fix warnings when generating ReadTheDocs #1509</li> <li>Remove Streetcred references #1504</li> <li>Add RTD configs to get generator working #1496</li> <li>The Alice/Faber demo was updated to allow connections based on Public DIDs to be established, including reusing a connection if there is an existing connection. #1574</li> <li>Other Fixes</li> <li>Connection Handling / Out of Band Invitations Fixes<ul> <li>OOB: Fixes issues with multiple public explicit invitation and unused 0160 connection #1525</li> <li>OOB added webhooks to notify the controller when a connection reuse message is used in response to an invitation #1581</li> <li>Delete unused ConnRecord generated - OOB invitation (use_exising_connection) #1521</li> <li>When an invitee responded with a \"reuse\" message, the connection record associated with the invitation was not being deleted. Now it is.</li> <li>Await asyncio.sleeps to cleanup warnings in Python 3.8/3.9 #1558</li> <li>Add alias field to didexchange invitation UI #1561</li> <li>fix: use invitation key for connection query #1570</li> <li>Fix the inconsistency of invitation_msg_id between invitation and response #1564</li> <li>chore: update pydid to ^0.3.3 #1562</li> </ul> </li> <li>DIF Presentation Exchange Cleanups<ul> <li>Fix DIF Presentation Request Input Validation #1517</li> <li>Some validation checking of a DIF presentation request to prevent uncaught errors later in the process.</li> <li>DIF PresExch - ProblemReport and \"is_holder\" #1493</li> <li>Cleanups related to when \"is_holder\" is or is not required. Related to Issue #1486</li> </ul> </li> <li>Indy SDK Related Fixes<ul> <li>Fix AttributeError when writing an Indy Cred Def record #1516</li> <li>Fix TypeError when calling credential_definitions_fix_cred_def_wallet\u2026 #1515</li> <li>Fix TypeError when writing a Schema record #1494</li> <li>Fix validation for range checks #1538</li> <li>Back out some of the validation checking for proof requests with predicates as they were preventing valid proof requests from being processed.</li> </ul> </li> <li>Aries Askar Related Fixes:<ul> <li>Fix bug when getting credentials on askar-profile #1510</li> <li>Fix error when removing a wallet on askar-profile #1518</li> <li>Fix error when connection request is received (askar, public invitation) #1508</li> <li>Fix error when an error occurs while issuing a revocable credential #1591</li> </ul> </li> <li>Docker fixes:<ul> <li>Update docker scripts to use new &amp; improved docker IP detection #1565</li> </ul> </li> <li>Release Adminstration:<ul> <li>Changelog and RTD updates for the pending 0.7.3 release #1553</li> </ul> </li> </ul>"},{"location":"CHANGELOG/#072","title":"0.7.2","text":""},{"location":"CHANGELOG/#november-15-2021","title":"November 15, 2021","text":"<p>A mostly maintenance release with some key updates and cleanups based on community deployments and discovery. With usage in the field increasing, we're cleaning up edge cases and issues related to volume deployments.</p> <p>The most significant new feature for users of Indy ledgers is a simplified approach for transaction authors getting their transactions signed by an endorser. Transaction author controllers now do almost nothing other than configuring their instance to use an Endorser, and ACA-Py takes care of the rest. Documentation of that feature is here.</p> <ul> <li>Improve cloud native deployments/scaling</li> <li>unprotect liveness and readiness endpoints #1416</li> <li>Open askar sessions only on demand - Connections #1424</li> <li>Fixed potential deadlocks by opening sessions only on demand (Wallet endpoints) #1472</li> <li>Fixed potential deadlocks by opening sessions only on demand #1439</li> <li>Make mediation invitation parameter idempotent #1413</li> <li>Indy Transaction Endorser Support Added</li> <li>Endorser protocol configuration, automation and demo integration #1422</li> <li>Auto connect from author to endorser on startup #1461</li> <li>Startup and shutdown events (prep for endorser updates) #1459</li> <li>Endorser protocol askar fixes #1450</li> <li>Endorser protocol updates - refactor to use event bus #1448</li> <li>Indy verifiable credential/presentation fixes and updates</li> <li>Update credential and proof mappings to allow negative encoded values #1475</li> <li>Add credential validation to offer issuance step #1446</li> <li>Fix error removing proof req entries by timestamp #1465</li> <li>Fix issue with cred limit on presentation endpoint #1437</li> <li>Add support for custom offers from the proposal #1426</li> <li>Make requested attributes and predicates required on indy proof request #1411</li> <li>Remove connection check on proof verify #1383</li> <li>General cleanups and improvements to existing features</li> <li>Fixes failing integration test -- JSON-LD context URL not loading because of external issue #1491</li> <li>Update base record time-stamp to standard ISO format #1453</li> <li>Encode DIDComm messages before sent to the queue #1408</li> <li>Add Event bus Metadata #1429</li> <li>Allow base wallet to connect to a mediator after startup #1463</li> <li>Log warning when unsupported problem report code is received #1409</li> <li>feature/inbound-transport-profile #1407</li> <li>Import cleanups #1393</li> <li>Add no-op handler for generic ack message (RFC 0015) #1390</li> <li>Align OutOfBandManager.receive_invitation with other connection managers #1382</li> <li>Bug fixes</li> <li>fix: fixes error in use of a default mediator in connections/out of band -- mediation ID was being saved as None instead of the retrieved default mediator value #1490</li> <li>fix: help text for open-mediation flag #1445</li> <li>fix: incorrect return type #1438</li> <li>Add missing param to ws protocol #1442</li> <li>fix: create static doc use empty endpoint if None #1483</li> <li>fix: use named tuple instead of dataclass in mediation invite store #1476</li> <li>When fetching the admin config, don't overwrite webhook settings #1420</li> <li>fix: return type of inject #1392</li> <li>fix: typo in connection static result schema #1389</li> <li>fix: don't require push on outbound queue implementations #1387</li> <li>Updates/Fixes to the Alice/Faber demo and integration tests</li> <li>Clarify instructions in the Acme Controller Demo #1484</li> <li>Fix aip 20 behaviour and other cleanup #1406</li> <li>Fix issue with startup sequence for faber agent #1415</li> <li>Connectionless proof demo #1395</li> <li>Typos in the demo's README.md #1405</li> <li>Run integration tests using external ledger and tails server #1400</li> <li>Chores</li> <li>Update CONTRIBUTING.md #1428</li> <li>Update to ReadMe and Supported RFCs for 0.7.2 #1489</li> <li>Updating the RTDs code for Release 0.7.2 - Try 2 #1488</li> </ul>"},{"location":"CHANGELOG/#071","title":"0.7.1","text":""},{"location":"CHANGELOG/#august-31-2021","title":"August 31, 2021","text":"<p>A relatively minor maintenance release to address issues found since the 0.7.0 Release. Includes some cleanups of JSON-LD Verifiable Credentials and Verifiable Presentations</p> <ul> <li>W3C  Verifiable Credential cleanups</li> <li>Timezone inclusion [ISO 8601] for W3C VC and Proofs (#1373)</li> <li>W3C VC handling where attachment is JSON and not Base64 encoded (#1352)</li> <li>Refactor outbound queue interface (#1348)</li> <li>Command line parameter handling for arbitrary plugins (#1347)</li> <li>Add an optional parameter '--ledger-socks-proxy' (#1342)</li> <li>OOB Protocol - CredentialOffer Support (#1316), (#1216)</li> <li>Updated IndyCredPrecisSchema - pres_referents renamed to presentation_referents (#1334)</li> <li>Handle unpadded protected header in PackWireFormat::get_recipient_keys (#1324)</li> <li>Initial cut of OpenAPI Code Generation guidelines (#1339)</li> <li>Correct revocation API in credential revocation documentation (#612)</li> <li>Documentation updates for Read-The-Docs (#1359, #1366, #1371)</li> <li>Add <code>inject_or</code> method to dynamic injection framework to resolve typing ambiguity (#1376)</li> <li>Other fixes:</li> <li>Indy Proof processing fix, error not raised in predicate timestamp check (#1364)</li> <li>Problem Report handler for connection specific problems (#1356)</li> <li>fix: error on deserializing conn record with protocol (#1325)</li> <li>fix: failure to verify jsonld on non-conformant doc but vaild vmethod (#1301)</li> <li>fix: allow underscore in endpoints (#1378)</li> </ul>"},{"location":"CHANGELOG/#070","title":"0.7.0","text":""},{"location":"CHANGELOG/#july-14-2021","title":"July 14, 2021","text":"<p>Another significant release, this version adds support for multiple new protocols, credential formats, and extension methods.</p> <ul> <li>Support for W3C Standard Verifiable Credentials based on JSON-LD using LD-Signatures and BBS+ Signatures, contributed by Animo Solutions - #1061</li> <li>Present Proof V2 including support for DIF Presentation Exchange - #1125</li> <li>Pluggable DID Resolver (with a did:web resolver) with fallback to an external DID universal resolver, contributed by Indicio - #1070</li> <li>Updates and extensions to ledger transaction endorsement via the Sign Attachment Protocol, contributed by AyanWorks - #1134, #1200</li> <li>Upgrades to Demos to add support for Credential Exchange 2.0 and W3C Verifiable Credentials #1235</li> <li>Alpha support for the Indy/Aries Shared Components (indy-vdr, indy-credx and aries-askar), which enable running ACA-Py without using Indy-SDK, while still supporting the use of Indy as a ledger, and Indy AnonCreds verifiable credentials #1267</li> <li>A new event bus for distributing internally generated ACA-Py events to controllers and other listeners, contributed by Indicio - #1063</li> <li>Enable operation without Indy ledger support if not needed</li> <li>Performance fix for deployments with large numbers of DIDs/connections #1249</li> <li>Simplify the creation/handling of plugin protocols #1086, #1133, #1226</li> <li>DID Exchange implicit invitation handling #1174</li> <li>Add support for Indy 1.16 predicates (restrictions on predicates based on attribute name and value) #1213</li> <li>BDD Tests run via GitHub Actions #1046</li> </ul>"},{"location":"CHANGELOG/#060","title":"0.6.0","text":""},{"location":"CHANGELOG/#february-25-2021","title":"February 25, 2021","text":"<p>This is a significant release of ACA-Py with several new features, as well as changes to the internal architecture in order to set the groundwork for using the new shared component libraries: indy-vdr, indy-credx, and aries-askar.</p>"},{"location":"CHANGELOG/#mediator-support","title":"Mediator support","text":"<p>While ACA-Py had previous support for a basic routing protocol, this was never fully developed or used in practice. Starting with this release, inbound and outbound connections can be established through a mediator agent using the Aries Mediator Coordination Protocol. This work was initially contributed by Adam Burdett and Daniel Bluhm of Indicio on behalf of SICPA. Read more about mediation support.</p>"},{"location":"CHANGELOG/#multi-tenancy-support","title":"Multi-Tenancy support","text":"<p>Started by BMW and completed by Animo Solutions and Anon Solutions on behalf of SICPA, this feature allows for a single ACA-Py instance to host multiple wallet instances. This can greatly reduce the resources required when many identities are being handled. Read more about multi-tenancy support.</p>"},{"location":"CHANGELOG/#new-connection-protocols","title":"New connection protocol(s)","text":"<p>In addition to the Aries 0160 Connections RFC, ACA-Py now supports the Aries DID Exchange Protocol for connection establishment and reuse, as well as the Aries Out-of-Band Protocol for representing connection invitations and other pre-connection requests.</p>"},{"location":"CHANGELOG/#issue-credential-v2","title":"Issue-Credential v2","text":"<p>This release includes an initial implementation of the Aries Issue Credential v2 protocol.</p>"},{"location":"CHANGELOG/#notable-changes-for-administrators","title":"Notable changes for administrators","text":"<ul> <li> <p>There are several new endpoints available for controllers as well as new startup parameters related to the multi-tenancy and mediator features, see the feature description pages above in order to make use of these features. Additional admin endpoints are introduced for the DID Exchange, Issue Credential v2, and Out-of-Band protocols.</p> </li> <li> <p>When running <code>aca-py start</code>, a new wallet will no longer be created unless the <code>--auto-provision</code> argument is provided. It is recommended to always use <code>aca-py provision</code> to initialize the wallet rather than relying on automatic behaviour, as this removes the need for repeatedly providing the wallet seed value (if any). This is a breaking change from previous versions.</p> </li> <li> <p>When running <code>aca-py provision</code>, an existing wallet will not be removed and re-created unless the <code>--recreate-wallet</code> argument is provided. This is a breaking change from previous versions.</p> </li> <li> <p>The logic around revocation intervals has been tightened up in accordance with Present Proof Best Practices.</p> </li> </ul>"},{"location":"CHANGELOG/#notable-changes-for-plugin-writers","title":"Notable changes for plugin writers","text":"<p>The following are breaking changes to the internal APIs which may impact Python code extensions.</p> <ul> <li> <p>Manager classes generally accept a <code>Profile</code> instance, where previously they accepted a <code>RequestContext</code>.</p> </li> <li> <p>Admin request handlers now receive an <code>AdminRequestContext</code> as <code>app[\"context\"]</code>. The current profile is available as <code>app[\"context\"].profile</code>. The admin server now generates a unique context instance per request in order to facilitate multi-tenancy, rather than reusing the same instance for each handler.</p> </li> <li> <p>In order to inject the <code>BaseStorage</code> or <code>BaseWallet</code> interfaces, a <code>ProfileSession</code> must be used. Other interfaces can be injected at the <code>Profile</code> or <code>ProfileSession</code> level. This is obtained by awaiting <code>profile.session()</code> for the current <code>Profile</code> instance, or (preferably) using it as an async context manager:</p> </li> </ul> <p><code>python= async with profile.session() as session:    storage = session.inject(BaseStorage)</code></p> <ul> <li>The <code>inject</code> method of a context is no longer <code>async</code>.</li> </ul>"},{"location":"CHANGELOG/#056","title":"0.5.6","text":""},{"location":"CHANGELOG/#october-19-2020","title":"October 19, 2020","text":"<ul> <li>Fix an attempt to update the agent endpoint when configured with a read-only ledger #758</li> </ul>"},{"location":"CHANGELOG/#055","title":"0.5.5","text":""},{"location":"CHANGELOG/#october-9-2020","title":"October 9, 2020","text":"<ul> <li>Support interactions using the new <code>https://didcomm.org</code> message type prefix (currently opt-in via the <code>--emit-new-didcomm-prefix</code> flag) #705, #713</li> <li>Updates to application startup arguments, adding support for YAML configuration #739, #746, #748</li> <li>Add a new endpoint to check the revocation status of a stored credential #735</li> <li>Clean up API documentation and OpenAPI definition, minor API adjustments #712, #726, #732, #734, #738, #741, #747</li> <li>Add configurable support for unencrypted record tags #723</li> <li>Retain more limited records on issued credentials #718</li> <li>Fix handling of custom endpoint in connections <code>accept-request</code> API method #715,   #716</li> <li>Add restrictions around revocation registry sizes #727</li> <li>Allow the state for revocation registry records to be set manually #708</li> <li>Handle multiple matching credentials when satisfying a presentation request using <code>names</code> #706</li> <li>Additional handling for a missing local tails file, tails file rollover process #702, #717</li> <li>Handle unknown credential ID in <code>create-proof</code> API method #700</li> <li>Improvements to revocation interval handling in presentation requests #699, #703</li> <li>Clean up warnings on API redirects #692</li> <li>Extensions to DID publicity status #691</li> <li>Support Unicode text in JSON-LD credential handling #687</li> </ul>"},{"location":"CHANGELOG/#054","title":"0.5.4","text":""},{"location":"CHANGELOG/#august-24-2020","title":"August 24, 2020","text":"<ul> <li>Improvements to schema, cred def registration procedure #682, #683</li> <li>Updates to align admin API output with documented interface #674, #681</li> <li>Fix provisioning issue when ledger is configured as read-only #673</li> <li>Add <code>get-nym-role</code> action #671</li> <li>Basic support for w3c profile endpoint #667, #669</li> <li>Improve handling of non-revocation interval #648, #680</li> <li>Update revocation demo after changes to tails file handling #644</li> <li>Improve handling of fatal ledger errors #643, #659</li> <li>Improve <code>did:key:</code> handling in out-of-band protocol support #639</li> <li>Fix crash when no public DID is configured #637</li> <li>Fix high CPU usage when only messages pending retry are in the outbound queue #636</li> <li>Additional unit tests for config, messaging, revocation, startup, transports #633, #641, #658, #661, #666</li> <li>Allow forwarded messages to use existing connections and the outbound queue #631</li> </ul>"},{"location":"CHANGELOG/#053","title":"0.5.3","text":""},{"location":"CHANGELOG/#july-23-2020","title":"July 23, 2020","text":"<ul> <li>Store endpoint on provisioned DID records #610</li> <li>More reliable delivery of outbound messages and webhooks #615</li> <li>Improvements for OpenShift pod handling #614</li> <li>Remove support for 'on-demand' revocation registries #605</li> <li>Sort tags in generated swagger JSON for better consistency #602</li> <li>Improve support for multi-credential proofs #601</li> <li>Adjust default settings for tracing and add documentation #598, #597</li> <li>Fix reliance on local copy of revocation tails file #590</li> <li>Improved handling of problem reports #595</li> <li>Remove credential preview parameter from credential issue endpoint #596</li> <li>Looser format restrictions on dates #586</li> <li>Support <code>names</code> and attribute-value specifications in present-proof protocol #587</li> <li>Misc documentation updates and unit test coverage</li> </ul>"},{"location":"CHANGELOG/#052","title":"0.5.2","text":""},{"location":"CHANGELOG/#june-26-2020","title":"June 26, 2020","text":"<ul> <li>Initial out-of-band protocol support #576</li> <li>Support provisioning a new local-only DID in the wallet, updating a DID endpoint #559, #573</li> <li>Support pagination for holder search operation #558</li> <li>Add raw JSON credential signing and verification admin endpoints #540</li> <li>Catch fatal errors in admin and protocol request handlers #527, #533, #534, #539, #543, #554, #555</li> <li>Add wallet and DID key rotation operations #525</li> <li>Admin API documentation and usability improvements #504, #516, #570</li> <li>Adjust the maximum number of attempts for outbound messages #501</li> <li>Add demo support for tails server #499</li> <li>Various credential and presentation protocol fixes and improvements #491, #494, #498, #526, #561, #563, #564, #577, #579</li> <li>Fixes for multiple agent endpoints #495, #497</li> <li>Additional test coverage #482, #485, #486, #487, #490, #493, #509, #553</li> <li>Update marshmallow dependency #479</li> </ul>"},{"location":"CHANGELOG/#051","title":"0.5.1","text":""},{"location":"CHANGELOG/#april-23-2020","title":"April 23, 2020","text":"<ul> <li>Restore previous response format for the <code>/credential/{id}</code> admin route #474</li> </ul>"},{"location":"CHANGELOG/#050","title":"0.5.0","text":""},{"location":"CHANGELOG/#april-21-2020","title":"April 21, 2020","text":"<ul> <li>Add support for credential revocation and revocation registry handling, with thanks to Medici Ventures #306, #417, #425, #429, #432, #435, #441, #455</li> <li>Breaking change Remove previous credential and presentation protocols (0.1 versions) #416</li> <li>Add support for major/minor protocol version routing #443</li> <li>Event tracing and trace reports for message exchanges #440</li> <li>Support additional Indy restriction operators (<code>&gt;</code>, <code>&lt;</code>, <code>&lt;=</code> in addition to <code>&gt;=</code>) #457</li> <li>Support signed attachments according to the updated Aries RFC 0017 #456</li> <li>Increased test coverage #442, #453</li> <li>Updates to demo agents and documentation #402, #403, #411, #415, #422, #423, #449, #450, #452</li> <li>Use Indy generate_nonce method to create proof request nonces #431</li> <li>Make request context available in the outbound transport handler #408</li> <li>Contain indy-anoncreds usage in IndyIssuer, IndyHolder, IndyProver classes #406, #463</li> <li>Fix issue with validation of proof with predicates and revocation support #400</li> </ul>"},{"location":"CHANGELOG/#045","title":"0.4.5","text":""},{"location":"CHANGELOG/#march-3-2020","title":"March 3, 2020","text":"<ul> <li>Added NOTICES file with license information for dependencies #398</li> <li>Updated documentation for administration API demo #397</li> <li>Accept self-attested attributes in presentation verification, only when no restrictions are present on the requested attribute #394, #396</li> </ul>"},{"location":"CHANGELOG/#044","title":"0.4.4","text":""},{"location":"CHANGELOG/#february-28-2020","title":"February 28, 2020","text":"<ul> <li>Update docker image used in demo and test containers #391</li> <li>Fix pre-verify check on received presentations #390</li> <li>Do not canonicalize attribute names in credential previews #389</li> </ul>"},{"location":"CHANGELOG/#043","title":"0.4.3","text":""},{"location":"CHANGELOG/#february-26-2020","title":"February 26, 2020","text":"<ul> <li>Fix the application of transaction author agreement acceptance to signed ledger requests #385</li> <li>Add a command line argument to preserve connection exchange records #355</li> <li>Allow custom credential IDs to be specified by the controller in the issue-credential protocol #384</li> <li>Handle send timeouts in the admin server websocket implementation #377</li> <li>Aries RFC 0348: Support the 'didcomm.org' message type prefix for incoming messages #379</li> <li>Add support for additional postgres wallet schemes such as \"MultiWalletDatabase\" #378</li> <li>Updates to the demo agents and documentation to support demos using the OpenAPI interface #371, #375, #376, #382, #383, #382</li> <li>Add a new flag for preventing writes to the ledger #364</li> </ul>"},{"location":"CHANGELOG/#042","title":"0.4.2","text":""},{"location":"CHANGELOG/#february-8-2020","title":"February 8, 2020","text":"<ul> <li>Adjust logging on HTTP request retries #363</li> <li>Tweaks to <code>run_docker</code>/<code>run_demo</code> scripts for Windows #357</li> <li>Avoid throwing exceptions on invalid or incomplete received presentations #359</li> <li>Restore the <code>present-proof/create-request</code> admin endpoint for creating connectionless presentation requests #356</li> <li>Activate the <code>connections/create-static</code> admin endpoint for creating static connections #354</li> </ul>"},{"location":"CHANGELOG/#041","title":"0.4.1","text":""},{"location":"CHANGELOG/#january-31-2020","title":"January 31, 2020","text":"<ul> <li>Update Forward messages and handlers to align with RFC 0094 for compatibility with libvcx and Streetcred #240, #349</li> <li>Verify encoded attributes match raw attributes on proof presentation #344</li> <li>Improve checks for existing credential definitions in the wallet and on ledger when publishing #333, #346</li> <li>Accommodate referents in presentation proposal preview attribute specifications #333</li> <li>Make credential proposal optional in issue-credential protocol #336</li> <li>Handle proofs with repeated credential definition IDs #330</li> <li>Allow side-loading of alternative inbound transports #322</li> <li>Various fixes to documentation and message schemas, and improved unit test coverage</li> </ul>"},{"location":"CHANGELOG/#040","title":"0.4.0","text":""},{"location":"CHANGELOG/#december-10-2019","title":"December 10, 2019","text":"<ul> <li>Improved unit test coverage (actionmenu, basicmessage, connections, introduction, issue-credential, present-proof, routing protocols)</li> <li>Various documentation and bug fixes</li> <li>Add admin routes for fetching and accepting the ledger transaction author agreement #144</li> <li>Add support for receiving connection-less proof presentations #296</li> <li>Set attachment id explicitly in unbound proof request #289</li> <li>Add create-proposal admin endpoint to the present-proof protocol #288</li> <li>Remove old anon/authcrypt support #282</li> <li>Allow additional endpoints to be specified #276</li> <li>Allow timestamp without trailing 'Z' #275, #277</li> <li>Display agent label and version on CLI and SwaggerUI #274</li> <li>Remove connection activity tracking and add ping webhooks (with --monitor-ping) #271</li> <li>Refactor message transport to track all async tasks, active message handlers #269, #287</li> <li>Add invitation mode \"static\" for static connections #260</li> <li>Allow for cred proposal underspecification of cred def id, only lock down cred def id at issuer on offer. Sync up api requests to Aries RFC-36 verbiage #259</li> <li>Disable cookies on outbound requests (avoid session affinity) #258</li> <li>Add plugin registry for managing all loaded protocol plugins, streamline ClassLoader #257, #261</li> <li>Add support for locking a cache key to avoid repeating expensive operations #256</li> <li>Add optional support for uvloop #255</li> <li>Output timing information when --timing-log argument is provided #254</li> <li>General refactoring - modules moved from messaging into new core, protocols, and utils sub-packages #250, #301</li> <li>Switch performance demo to the newer issue-credential protocol #243</li> </ul>"},{"location":"CHANGELOG/#035","title":"0.3.5","text":""},{"location":"CHANGELOG/#november-1-2019","title":"November 1, 2019","text":"<ul> <li>Switch performance demo to the newer issue-credential protocol #243</li> <li>Remove old method for reusing credential requests and replace with local caching for credential offers and requests #238, #242</li> <li>Add statistics on HTTP requests to timing output #237</li> <li>Reduce the number of tags on non-secrets records to reduce storage requirements and improve performance #235</li> </ul>"},{"location":"CHANGELOG/#034","title":"0.3.4","text":""},{"location":"CHANGELOG/#october-23-2019","title":"October 23, 2019","text":"<ul> <li>Clean up base64 handling in wallet utils and add tests #224</li> <li>Support schema sequence numbers for lookups and caching and allow credential definition tag override via admin API #223</li> <li>Support multiple proof referents in the present-proof protocol #222</li> <li>Group protocol command line arguments appropriately #217</li> <li>Don't require a signature for get_txn_request in credential_definition_id2schema_id and reduce public DID lookups #215</li> <li>Add a role property to credential exchange and presentation exchange records #214, #218</li> <li>Improve attachment decorator handling #210</li> <li>Expand and correct documentation of the OpenAPI interface #208, #212</li> </ul>"},{"location":"CHANGELOG/#033","title":"0.3.3","text":""},{"location":"CHANGELOG/#september-27-2019","title":"September 27, 2019","text":"<ul> <li>Clean up LGTM errors and warnings and fix a message dispatch error #203</li> <li>Avoid wrapping messages with Forward wrappers when returning them directly #199</li> <li>Add a CLI parameter to override the base URL used in URL-formatted connection invitations #197</li> <li>Update the feature discovery protocol to match the RFC and rename the admin API endpoint #193</li> <li>Add CLI parameters for specifying additional properties of the printed connection invitation #192</li> <li>Add support for explicitly setting the wallet credential ID on storage #188</li> <li>Additional performance tracking and storage reductions #187</li> <li>Handle connection invitations in base64 or URL format in the Alice demo agent #186</li> <li>Add admin API methods to get and set the credential tagging policy for a credential definition ID #185</li> <li>Allow querying of credentials for proof requests with multiple referents #181</li> <li>Allow self-connected agents to issue credentials, present proofs #179</li> <li>Add admin API endpoints to register a ledger nym, fetch a ledger DID verkey, or fetch a ledger DID endpoint #178</li> </ul>"},{"location":"CHANGELOG/#032","title":"0.3.2","text":""},{"location":"CHANGELOG/#september-3-2019","title":"September 3, 2019","text":"<ul> <li>Merge support for Aries #36 (issue-credential) and Aries #37 (present-proof) protocols #164, #167</li> <li>Add <code>initiator</code> to connection record queries to ensure uniqueness in the case of a self-connection #161</li> <li>Add connection aliases #149</li> <li>Misc documentation updates</li> </ul>"},{"location":"CHANGELOG/#031","title":"0.3.1","text":""},{"location":"CHANGELOG/#august-15-2019","title":"August 15, 2019","text":"<ul> <li>Do not fail with an error when no ledger is configured #145</li> <li>Switch to PyNaCl instead of pysodium; update dependencies #143</li> <li>Support reusable connection invitations #142</li> <li>Fix --version option and optimize Docker builds #136</li> <li>Add connection_id to basicmessage webhooks #134</li> <li>Fixes for transaction author agreements #133</li> </ul>"},{"location":"CHANGELOG/#030","title":"0.3.0","text":""},{"location":"CHANGELOG/#august-9-2019","title":"August 9, 2019","text":"<ul> <li>Ledger and wallet config updates; add support for transaction author agreements #127</li> <li>Handle duplicate schema in send_schema by always fetching first #126</li> <li>More flexible timeout support in detect_process #125</li> <li>Add start command to run_docker invocations #119</li> <li>Add issuer stored state #114</li> <li>Add admin route to create a presentation request without sending it #112</li> <li>Add -v option to aca-py executable to print version #110</li> <li>Fix demo presentation request, optimize credential retrieval #108</li> <li>Add pypi badge to README and make document link URLs absolute #103</li> <li>Add admin routes for creating and listing wallet DIDs, adjusting the public DID #102</li> <li>Update the running locally instructions based on feedback from Sam Smith #101</li> <li>Add support for multiple invocation commands, implement start/provision/help commands #99</li> <li>Add admin endpoint to send problem report #98</li> <li>Add credential received state transition #97</li> <li>Adding documentation for the routing version of the performance example #94</li> <li>Document listing the Aries RFCs supported by ACA-Py and reference to the list in the README #89</li> <li>Further updates to the running locally section of the demo README #86</li> <li>Don't extract decorators with names matching the 'data_key' of defined schema fields #85</li> <li>Allow demo scripts to run outside of Docker; add command line parsing #84</li> <li>Connection invitation fixes and improvements; support DID-based invitations #82</li> </ul>"},{"location":"CHANGELOG/#021","title":"0.2.1","text":""},{"location":"CHANGELOG/#july-16-2019","title":"July 16, 2019","text":"<ul> <li>Add missing MANIFEST file #78</li> </ul>"},{"location":"CHANGELOG/#020","title":"0.2.0","text":""},{"location":"CHANGELOG/#july-16-2019_1","title":"July 16, 2019","text":"<p>This is the first PyPI release. The history begins with the transfer of aca-py from bcgov to hyperledger.</p> <ul> <li>Prepare for version 0.2.0 release #77</li> <li>Update von-network related references. #74</li> <li>Fixed log_level arg, added validation error logging #73</li> <li>fix shell inconsistency #72</li> <li>further cleanup to the OpenAPI demo script #71</li> <li>Updates to invitation handling and performance test #68</li> <li>Api security #67</li> <li>Fix line endings on Windows #66</li> <li>Fix repository name in badge links #65</li> <li>Connection record is_ready refactor #64</li> <li>Fix API instructions for cred def id #58</li> <li>Updated API demo docs to use alice/faber scripts #54</li> <li>Updates to the readme for the demo to add PWD support #53</li> <li>Swallow empty input in demo scripts #51</li> <li>Set credential_exchange state when created from a cached credential request #49</li> <li>Check for readiness instead of activeness in credential admin routes #46</li> <li>Demo updates #43</li> <li>Misc fixes #42</li> <li>Readme updates #41</li> <li>Change installed \"binary\" name to aca-py #40</li> <li>Tweak in script to work under Linux; updates to readme for demo #33</li> <li>New routing example document, typo corrections #31</li> <li>More bad links #30</li> <li>Links cleanup for the documentation #29</li> <li>Alice-Faber demo update #28</li> <li>Deployment Model document #27</li> <li>Plantuml source and images for documentation; w/image generator script #26</li> <li>Move generated documentation. #25</li> <li>Update generated documents #24</li> <li>Split application configuration into separate modules and add tests #23</li> <li>Updates to the RTD configuration file #22</li> <li>Merge DIDDoc support from von_anchor #21</li> <li>Adding Prov of BC, Gov of Canada copyright #19</li> <li>Update test configuration #18</li> <li>CI updates #17</li> <li>Transport updates #15</li> </ul>"},{"location":"CODE_OF_CONDUCT/","title":"Hyperledger Code of Conduct","text":"<p>Hyperledger is a collaborative project at The Linux Foundation. It is an open-source and open community project where participants choose to work together, and in that process experience differences in language, location, nationality, and experience. In such a diverse environment, misunderstandings and disagreements happen, which in most cases can be resolved informally. In rare cases, however, behavior can intimidate, harass, or otherwise disrupt one or more people in the community, which Hyperledger will not tolerate.</p> <p>A Code of Conduct is useful to define accepted and acceptable behaviors and to promote high standards of professional practice. It also provides a benchmark for self evaluation and acts as a vehicle for better identity of the organization.</p> <p>This code (CoC) applies to any member of the Hyperledger community \u2013 developers, participants in meetings, teleconferences, mailing lists, conferences or functions, etc. Note that this code complements rather than replaces legal rights and obligations pertaining to any particular situation.</p>"},{"location":"CODE_OF_CONDUCT/#statement-of-intent","title":"Statement of Intent","text":"<p>Hyperledger is committed to maintain a positive work environment. This commitment calls for a workplace where participants at all levels behave according to the rules of the following code. A foundational concept of this code is that we all share responsibility for our work environment.</p>"},{"location":"CODE_OF_CONDUCT/#code","title":"Code","text":"<ol> <li> <p>Treat each other with respect, professionalism, fairness, and sensitivity to our many    differences and strengths, including in situations of high pressure and urgency.</p> </li> <li> <p>Never harass or bully anyone verbally, physically or    sexually.</p> </li> <li> <p>Never discriminate on the basis of personal characteristics or group    membership.</p> </li> <li> <p>Communicate constructively and avoid demeaning or    insulting behavior or language.</p> </li> <li> <p>Seek, accept, and offer objective work criticism, and acknowledge properly    the contributions of others.</p> </li> <li> <p>Be honest about your own qualifications, and about any circumstances that might lead to conflicts    of interest.</p> </li> <li> <p>Respect the privacy of others and the confidentiality of data you access.</p> </li> <li> <p>With respect to cultural differences, be conservative in what you do and liberal in what you    accept from others, but not to the point of accepting disrespectful, unprofessional or unfair or    unwelcome behavior or advances.</p> </li> <li> <p>Promote the rules of this Code and take action (especially if you are in a    leadership position) to bring the discussion back to a more civil level    whenever inappropriate behaviors are observed.</p> </li> <li> <p>Stay on topic: Make sure that you are posting to the correct channel and avoid off-topic     discussions. Remember when you update an issue or respond to an email you are potentially     sending to a large number of people.</p> </li> <li> <p>Step down considerately: Members of every project come and go, and the Hyperledger is no     different. When you leave or disengage from the project, in whole or in part, we ask that you do     so in a way that minimizes disruption to the project. This means you should tell people you are     leaving and take the proper steps to ensure that others can pick up where you left off.</p> </li> </ol>"},{"location":"CODE_OF_CONDUCT/#glossary","title":"Glossary","text":""},{"location":"CODE_OF_CONDUCT/#demeaning-behavior","title":"Demeaning Behavior","text":"<p>is acting in a way that reduces another person's dignity, sense of self-worth or respect within the community.</p>"},{"location":"CODE_OF_CONDUCT/#discrimination","title":"Discrimination","text":"<p>is the prejudicial treatment of an individual based on criteria such as: physical appearance, race, ethnic origin, genetic differences, national or social origin, name, religion, gender, sexual orientation, family or health situation, pregnancy, disability, age, education, wealth, domicile, political view, morals, employment, or union activity.</p>"},{"location":"CODE_OF_CONDUCT/#insulting-behavior","title":"Insulting Behavior","text":"<p>is treating another person with scorn or disrespect.</p>"},{"location":"CODE_OF_CONDUCT/#acknowledgement","title":"Acknowledgement","text":"<p>is a record of the origin(s) and author(s) of a contribution.</p>"},{"location":"CODE_OF_CONDUCT/#harassment","title":"Harassment","text":"<p>is any conduct, verbal or physical, that has the intent or effect of interfering with an individual, or that creates an intimidating, hostile, or offensive environment.</p>"},{"location":"CODE_OF_CONDUCT/#leadership-position","title":"Leadership Position","text":"<p>includes group Chairs, project maintainers, staff members, and Board members.</p>"},{"location":"CODE_OF_CONDUCT/#participant","title":"Participant","text":"<p>includes the following persons:</p> <ul> <li>Developers</li> <li>Member representatives</li> <li>Staff members</li> <li>Anyone from the Public partaking in the Hyperledger work environment (e.g. contribute code,   comment on our code or specs, email us, attend our conferences, functions, etc)</li> </ul>"},{"location":"CODE_OF_CONDUCT/#respect","title":"Respect","text":"<p>is the genuine consideration you have for someone (if only because of their status as participant in Hyperledger, like yourself), and that you show by treating them in a polite and kind way.</p>"},{"location":"CODE_OF_CONDUCT/#sexual-harassment","title":"Sexual Harassment","text":"<p>includes visual displays of degrading sexual images, sexually suggestive conduct, offensive remarks of a sexual nature, requests for sexual favors, unwelcome physical contact, and sexual assault.</p>"},{"location":"CODE_OF_CONDUCT/#unwelcome-behavior","title":"Unwelcome Behavior","text":"<p>Hard to define? Some questions to ask yourself are:</p> <ul> <li>how would I feel if I were in the position of the recipient?</li> <li>would my spouse, parent, child, sibling or friend like to be treated this way?</li> <li>would I like an account of my behavior published in the organization's newsletter?</li> <li>could my behavior offend or hurt other members of the work group?</li> <li>could someone misinterpret my behavior as intentionally harmful or harassing?</li> <li>would I treat my boss or a person I admire at work like that ?</li> <li>Summary: if you are unsure whether something might be welcome or unwelcome, don't do it.</li> </ul>"},{"location":"CODE_OF_CONDUCT/#unwelcome-sexual-advance","title":"Unwelcome Sexual Advance","text":"<p>includes requests for sexual favors, and other verbal or physical conduct of a sexual nature, where:</p> <ul> <li>submission to such conduct is made either explicitly or implicitly a term or condition of an   individual's employment,</li> <li>submission to or rejection of such conduct by an individual is used as a basis for employment   decisions affecting the individual,</li> <li>such conduct has the purpose or effect of unreasonably interfering with an individual's work   performance or creating an intimidating hostile or offensive working environment.</li> </ul>"},{"location":"CODE_OF_CONDUCT/#workplace-bullying","title":"Workplace Bullying","text":"<p>is a tendency of individuals or groups to use persistent aggressive or unreasonable behavior (e.g. verbal or written abuse, offensive conduct or any interference which undermines or impedes work) against a co-worker or any professional relations.</p>"},{"location":"CODE_OF_CONDUCT/#work-environment","title":"Work Environment","text":"<p>is the set of all available means of collaboration, including, but not limited to messages to mailing lists, private correspondence, Web pages, chat channels, phone and video teleconferences, and any kind of face-to-face meetings or discussions.</p>"},{"location":"CODE_OF_CONDUCT/#incident-procedure","title":"Incident Procedure","text":"<p>To report incidents or to appeal reports of incidents, send email to Mike Dolan (mdolan@linuxfoundation.org) or Angela Brown (angela@linuxfoundation.org). Please include any available relevant information, including links to any publicly accessible material relating to the matter. Every effort will be taken to ensure a safe and collegial environment in which to collaborate on matters relating to the Project. In order to protect the community, the Project reserves the right to take appropriate action, potentially including the removal of an individual from any and all participation in the project. The Project will work towards an equitable resolution in the event of a misunderstanding.</p>"},{"location":"CODE_OF_CONDUCT/#credits","title":"Credits","text":"<p>This code is based on the W3C\u2019s Code of Ethics and Professional Conduct with some additions from the Cloud Foundry\u2018s Code of Conduct.</p>"},{"location":"CONTRIBUTING/","title":"How to contribute","text":"<p>You are encouraged to contribute to the repository by forking and submitting a pull request.</p> <p>For significant changes, please open an issue first to discuss the proposed changes to avoid re-work.</p> <p>(If you are new to GitHub, you might start with a basic tutorial and check out a more detailed guide to pull requests.)</p> <p>Pull requests will be evaluated by the repository guardians on a schedule and if deemed beneficial will be committed to the <code>main</code> branch. Pull requests should have a descriptive name, include a summary of all changes made in the pull request description, and include unit tests that provide good coverage of the feature or fix. A Continuous Integration (CI) pipeline is executed on all PRs before review and contributors are expected to address all CI issues identified. Where appropriate, PRs that impact the end-user and developer demos in the repo should include updates or extensions to those demos to cover the new capabilities.</p> <p>If you would like to propose a significant change, please open an issue first to discuss the work with the community.</p> <p>Contributions are made pursuant to the Developer's Certificate of Origin, available at https://developercertificate.org, and licensed under the Apache License, version 2.0 (Apache-2.0).</p>"},{"location":"CONTRIBUTING/#development-tools","title":"Development Tools","text":""},{"location":"CONTRIBUTING/#pre-commit","title":"Pre-commit","text":"<p>A configuration for pre-commit is included in this repository. This is an optional tool to help contributors commit code that follows the formatting requirements enforced by the CI pipeline. Additionally, it can be used to help contributors write descriptive commit messages that can be parsed by changelog generators.</p> <p>On each commit, pre-commit hooks will run that verify the committed code complies with ruff and is formatted with black. To install the ruff and black checks:</p> <pre><code>pre-commit install\n</code></pre> <p>To install the commit message linter:</p> <pre><code>pre-commit install --hook-type commit-msg\n</code></pre>"},{"location":"MAINTAINERS/","title":"Maintainers","text":""},{"location":"MAINTAINERS/#maintainer-scopes-github-roles-and-github-teams","title":"Maintainer Scopes, GitHub Roles and GitHub Teams","text":"<p>Maintainers are assigned the following scopes in this repository:</p> Scope Definition GitHub Role GitHub Team Admin Admin aries-admins Maintainer The GitHub Maintain role Maintain aries-cloudagent-python committers Triage The GitHub Triage role Triage aries triage Read The GitHub Read role Read Aries Contributors Read The GitHub Read role Read TOC Read The GitHub Read role Read aries-framework-go-ext committers"},{"location":"MAINTAINERS/#active-maintainers","title":"Active Maintainers","text":"GitHub ID Name Scope LFID Discord ID Email Company Affiliation andrewwhitehead Andrew Whitehead Admin cywolf@gmail.com BC Gov dbluhm Daniel Bluhm Admin daniel@indicio.tech Indicio PBC dhh1128 Daniel Hardman Admin daniel.hardman@gmail.com Provident shaangill025 Shaanjot Gill Maintainer gill.shaanjots@gmail.com BC Gov swcurran Stephen Curran Admin swcurran@cloudcompass.ca BC Gov TelegramSam Sam Curren Maintainer telegramsam@gmail.com Indicio PBC TimoGlastra Timo Glastra Admin timo@animo.id Animo Solutions WadeBarnes Wade Barnes Admin wade@neoterictech.ca BC Gov usingtechnology Jason Sherman Maintainer tools@usingtechnolo.gy BC Gov"},{"location":"MAINTAINERS/#emeritus-maintainers","title":"Emeritus Maintainers","text":"Name GitHub ID Scope LFID Discord ID Email Company Affiliation"},{"location":"MAINTAINERS/#the-duties-of-a-maintainer","title":"The Duties of a Maintainer","text":"<p>Maintainers are expected to perform the following duties for this repository. The duties are listed in more or less priority order:</p> <ul> <li>Review, respond, and act on any security vulnerabilities reported against the repository.</li> <li>Review, provide feedback on, and merge or reject GitHub Pull Requests from   Contributors.</li> <li>Review, triage, comment on, and close GitHub Issues   submitted by Contributors.</li> <li>When appropriate, lead/facilitate architectural discussions in the community.</li> <li>When appropriate, lead/facilitate the creation of a product roadmap.</li> <li>Create, clarify, and label issues to be worked on by Contributors.</li> <li>Ensure that there is a well defined (and ideally automated) product test and   release pipeline, including the publication of release artifacts.</li> <li>When appropriate, execute the product release process.</li> <li>Maintain the repository CONTRIBUTING.md file and getting started documents to   give guidance and encouragement to those wanting to contribute to the product, and those wanting to become maintainers.</li> <li>Contribute to the product via GitHub Pull Requests.</li> <li>Monitor requests from the Hyperledger Technical Oversight Committee about the contents and management of Hyperledger repositories, such as branch handling, required files in repositories and so on.</li> <li>Contribute to the Hyperledger Project's Quarterly Report.</li> </ul>"},{"location":"MAINTAINERS/#becoming-a-maintainer","title":"Becoming a Maintainer","text":"<p>This community welcomes contributions. Interested contributors are encouraged to progress to become maintainers. To become a maintainer the following steps occur, roughly in order.</p> <ul> <li>The proposed maintainer establishes their reputation in the community,   including authoring five (5) significant merged pull requests, and expresses   an interest in becoming a maintainer for the repository.</li> <li>A PR is created to update this file to add the proposed maintainer to the list of active maintainers.</li> <li>The PR is authored by an existing maintainer or has a comment on the PR from an existing maintainer supporting the proposal.</li> <li>The PR is authored by the proposed maintainer or has a comment on the PR from the proposed maintainer confirming their interest in being a maintainer.</li> <li>The PR or comment from the proposed maintainer must include their     willingness to be a long-term (more than 6 month) maintainer.</li> <li>Once the PR and necessary comments have been received, an approval timeframe begins.</li> <li>The PR MUST be communicated on all appropriate communication channels, including relevant community calls, chat channels and mailing lists. Comments of support from the community are welcome.</li> <li>The PR is merged and the proposed maintainer becomes a maintainer if either:</li> <li>Two weeks have passed since at least three (3) Maintainer PR approvals have been recorded, OR</li> <li>An absolute majority of maintainers have approved the PR.</li> <li>If the PR does not get the requisite PR approvals, it may be closed.</li> <li>Once the add maintainer PR has been merged, any necessary updates to the GitHub Teams are made.</li> </ul>"},{"location":"MAINTAINERS/#removing-maintainers","title":"Removing Maintainers","text":"<p>Being a maintainer is not a status symbol or a title to be carried indefinitely. It will occasionally be necessary and appropriate to move a maintainer to emeritus status. This can occur in the following situations:</p> <ul> <li>Resignation of a maintainer.</li> <li>Violation of the Code of Conduct warranting removal.</li> <li>Inactivity.</li> <li>A general measure of inactivity will be no commits or code review comments     for one reporting quarter. This will not be strictly enforced if     the maintainer expresses a reasonable intent to continue contributing.</li> <li>Reasonable exceptions to inactivity will be granted for known long term     leave such as parental leave and medical leave.</li> <li>Other circumstances at the discretion of the other Maintainers.</li> </ul> <p>The process to move a maintainer from active to emeritus status is comparable to the process for adding a maintainer, outlined above. In the case of voluntary resignation, the Pull Request can be merged following a maintainer PR approval. If the removal is for any other reason, the following steps SHOULD be followed:</p> <ul> <li>A PR is created to update this file to move the maintainer to the list of emeritus maintainers.</li> <li>The PR is authored by, or has a comment supporting the proposal from, an existing maintainer or Hyperledger GitHub organization administrator.</li> <li>Once the PR and necessary comments have been received, the approval timeframe begins.</li> <li>The PR MAY be communicated on appropriate communication channels, including relevant community calls, chat channels and mailing lists.</li> <li>The PR is merged and the maintainer transitions to maintainer emeritus if:</li> <li>The PR is approved by the maintainer to be transitioned, OR</li> <li>Two weeks have passed since at least three (3) Maintainer PR approvals have been recorded, OR</li> <li>An absolute majority of maintainers have approved the PR.</li> <li>If the PR does not get the requisite PR approvals, it may be closed.</li> </ul> <p>Returning to active status from emeritus status uses the same steps as adding a new maintainer. Note that the emeritus maintainer already has the 5 required significant changes as there is no contribution time horizon for those.</p>"},{"location":"PUBLISHING/","title":"How to Publish a New Version","text":"<p>The code to be published should be in the <code>main</code> branch. Make sure that all the PRs to go in the release are merged, and decide on the release tag. Should it be a release candidate or the final tag, and should it be a major, minor or patch release, per semver rules.</p> <p>Once ready to do a release, create a local branch that includes the following updates:</p> <ol> <li> <p>Create a PR branch from an updated <code>main</code> branch.</p> </li> <li> <p>Update the CHANGELOG.md to add the new release.  Only create a new section when working on the first release candidate for a new release. When transitioning from one release candidate to the next, or to an official release, just update the title and date of the change log section.</p> </li> <li> <p>Include details of the merged PRs included in this release. General process to follow:</p> </li> <li> <p>Gather the set of PRs since the last release and put them into a list. A good   tool to use for this is the   github-changelog-generator.   Steps:</p> </li> <li>Create a read only GitHub token for your account on this page:     https://github.com/settings/tokens     with a scope of <code>repo</code> / <code>public_repo</code>.</li> <li>Use a command like the following, adjusting the tag parameters as     appropriate. <code>docker run -it --rm -v \"$(pwd)\":/usr/local/src/your-app     githubchangeloggenerator/github-changelog-generator --user hyperledger     --project aries-cloudagent-python --output 0.11.0rc2.md --since-tag 0.10.4     --future-release 0.11.1rc2 --release-branch main --token &lt;your-token&gt;</code></li> <li>In the generated file, use only the PR list -- we don't include the list of     closed issues in the Change Log.</li> </ol> <p>In some cases, the approach above fails because of too many API calls. An alternate approach to getting the list of PRs in the right format is to use OpenAI ChatGPT.</p> <p>Prepare the following ChatGPT request. Don't hit enter yet--you have to add the data.</p> <p><code>Generate from this the github pull request number, the github id of the author and the title of the pull request in a tab-delimited list</code></p> <p>Get a list of the merged PRs since the last release by displaying the PR list in the GitHub UI, highlighting/copying the PRs and pasting them below the ChatGPT request, one page after another. Hit <code>&lt;Enter&gt;</code>, let the AI magic work, and you should have a list of the PRs in a nice table with a <code>Copy</code> link that you should click.</p> <p>Once you have that, open this Google Sheet and highlight the <code>A1</code> cell and paste in the ChatGPT data. A formula in column <code>E</code> will have the properly formatted changelog entries. Double check the list with the GitHub UI to make sure that ChatGPT isn't messing with you and you have the needed data.</p> <p>If using ChatGPT doesn't appeal to you, try this scary <code>sed</code>/command line approach:</p> <ul> <li>Put the following commands into a file called <code>changelog.sed</code></li> </ul> <pre><code>/Approved/d\n/updated /d\n/^$/d\n/^ [0-9]/d\ns/was merged.*//\n/^@/d\ns# by \\(.*\\) # [\\1](https://github.com/\\1)#\ns/^ //\ns#  \\#\\([0-9]*\\)# [\\#\\1](https://github.com/hyperledger/aries-cloudagent-python/pull/\\1) #\ns/  / /g\n/^Version/d\n/tasks done/d\ns/^/- /\n</code></pre> <ul> <li>Navigate in your browser to the paged list of PRs merged since the last   release (using in the GitHub UI a filter such as <code>is:pr is:merged sort:updated   merged:&gt;2022-04-07</code>) and for each page, highlight, and copy the text   of only the list of PRs on the page to use in the following step.</li> <li>For each page, run the command   <code>sed -e :a -e '$!N;s/\\n#/ #/;ta' -e 'P;D' &lt;&lt;EOF | sed -f changelog.sed</code>,   paste in the copied text and then type <code>EOF</code>.   Redirect the output to a file, appending each page of output to the file.</li> <li>The first <code>sed</code> command in the pipeline merges the PR title and PR number     plus author lines onto a single line. The commands in the <code>changelog.sed</code>     file just clean up the data, removing unwanted lines, etc.</li> <li>At the end of that process, you should have a list of all of the PRs in a form you can   use in the CHANGELOG.md file.</li> <li>To verify you have right number of PRs, you can do a <code>wc</code> of the file and there   should be one line per PR. You should scan the file as well, looking for   anomalies, such as missing <code>\\</code>s before <code>#</code> characters. It's a pretty ugly process.</li> <li>Using a <code>curl</code> command and the GitHub API is probably a much better and more   robust way to do this, but this was quick and dirty...</li> </ul> <p>Once you have the list of PRs:</p> <ul> <li>Organize the list into suitable categories, update (if necessary) the PR description and add notes to clarify the changes. See previous release entries to understand the style -- a format that should help developers.</li> <li> <p>Add a narrative about the release above the PR that highlights what has gone into the release.</p> </li> <li> <p>Check to see if there are any other PRs that should be included in the release.</p> </li> <li> <p>Update the ReadTheDocs in the <code>/docs</code> folder by following the instructions in    the <code>./README.md</code> file. That will likely add a number of new and modified    files to the PR. Eliminate all of the errors in the generation process,    either by mocking external dependencies or by fixing ACA-Py code. If    necessary, create an issue with the errors and assign it to the appropriate    developer. Experience has demonstrated to use that documentation generation    errors should be fixed in the code.</p> </li> <li> <p>Search across the repository for the previous version number and update it    everywhere that makes sense. The CHANGELOG.md is a likely exception, and the    <code>pyproject.toml</code> in the root is MUST. You can skip (although it won't    hurt) to update the files in the <code>open-api</code> folder as they will be    automagically updated by the next step in publishing. The incremented version    number MUST adhere to the Semantic Versioning    Specification    based on the changes since the last published release. For Release    Candidates, the form of the tag is \"0.11.0rc2\". As of release <code>0.11.0</code> we    have dropped the previously used <code>-</code> in the release candidate version string    to better follow the semver rules.</p> </li> <li> <p>Regenerate openapi.json and swagger.json by running    <code>./scripts/generate-open-api-spec</code>.</p> </li> <li> <p>Double check all of these steps above, and then submit a PR from the branch.    Add this new PR to CHANGELOG.md so that all the PRs are included.    If there are still further changes to be merged, mark the PR as \"Draft\",    repeat ALL of the steps again, and then mark this PR as ready and then    wait until it is merged. It's embarrassing when you have to do a whole new    release just because you missed something silly...I know!</p> </li> <li> <p>Immediately after it is merged, create a new GitHub tag representing the    version. The tag name and title of the release should be the same as the    version in pyproject.toml. Use    the \"Generate Release Notes\" capability to get a sequential listing of the    PRs in the release, to complement the manually curated Changelog. Verify on    PyPi that the version is published.</p> </li> <li> <p>New images for the release are automatically published by the GitHubAction    Workflows: publish.yml and publish-indy.yml. The actions are triggered    when a release is tagged, so no manual action is needed. The images are    published in the Hyperledger Package Repository under    aries-cloudagent-python    and a link to the packages added to the repositories main page (under    \"Packages\").</p> </li> </ul> <p>Additional information about the container image publication process can be    found in the document Container Images and Github Actions.</p> <ol> <li> <p>Update the ACA-Py Read The Docs site by building the new \"latest\" (main     branch) and activating and building the new release. Appropriate permissions     are required to publish the new documentation version.</p> </li> <li> <p>Update the https://aca-py.org website with the latest documentation by     creating a PR and tag of the latest documentation from this site. Details     are provided in the aries-acapy-docs repository.</p> </li> </ol>"},{"location":"SECURITY/","title":"Hyperledger Security Policy","text":""},{"location":"SECURITY/#reporting-a-security-bug","title":"Reporting a Security Bug","text":"<p>If you think you have discovered a security issue in any of the Hyperledger projects, we'd love to hear from you. We will take all security bugs seriously and if confirmed upon investigation we will patch it within a reasonable amount of time and release a public security bulletin discussing the impact and credit the discoverer.</p> <p>There are two ways to report a security bug. The easiest is to email a description of the flaw and any related information (e.g. reproduction steps, version) to security at hyperledger dot org.</p> <p>The other way is to file a confidential security bug in our JIRA bug tracking system. Be sure to set the \u201cSecurity Level\u201d to \u201cSecurity issue\u201d.</p> <p>The process by which the Hyperledger Security Team handles security bugs is documented further in our Defect Response page on our wiki.</p>"},{"location":"UpdateRTD/","title":"Managing Aries Cloud Agent Python <code>Read The Docs</code> Documentation","text":"<p>This document describes how to maintain the <code>Read The Docs</code> documentation that is generated from the ACA-Py code base. As the structure of the ACA-Py code evolves, the RTD files need to be regenerated and possibly updated, as described here.</p>"},{"location":"UpdateRTD/#generating-aca-py-read-the-docs-rtd-documentation","title":"Generating ACA-Py Read The Docs (RTD) documentation","text":""},{"location":"UpdateRTD/#before-you-start","title":"Before you start","text":"<p>To test generate and view the RTD documentation locally, you must install Sphinx and the Sphinx RTD theme. Follow the instructions on the respective pages to install and verify the installation on your system.</p>"},{"location":"UpdateRTD/#generate-module-files","title":"Generate Module Files","text":"<p>To rebuild the project and settings from scratch (you'll need to move the generated index file up a level):</p> <p><code>rm -rf generated; sphinx-apidoc -f -M -o  ./generated ../aries_cloudagent/ $(find ../aries_cloudagent/ -name '*tests*')</code></p> <p>Note that the <code>find</code> command that is used to exclude any of the <code>test</code> python files from the RTD documentation.</p> <p>Check the  <code>git status</code> in your repo to see if the generator updates, adds or removes any existing RTD modules.</p>"},{"location":"UpdateRTD/#reviewing-the-files-locally","title":"Reviewing the files locally","text":"<p>To auto-generate the module documentation locally run:</p> <pre><code>sphinx-build -b html -a -E -c ./ ./ ./_build\n</code></pre> <p>Once generated, go into the <code>_build</code> folder and open <code>index.html</code> in a browser. Note that the <code>_build</code> is <code>.gitignore</code>'d and so will not be part of a git push.</p>"},{"location":"UpdateRTD/#look-for-errors","title":"Look for Errors","text":"<p>This is the hard part; looking for errors in docstrings added by devs. Some tips:</p> <ul> <li>missing imports (<code>No module named 'async_timeout'</code>) can be solved by adding the module to the list of <code>autodoc_mock_imports</code> in the <code>conf.py</code> file in the ACA-Py <code>docs</code> folder.</li> <li>Ignore any errors in .md files</li> <li>Ignore the warnings about including <code>docs/README.md</code></li> <li>Ignore an dist-package errors</li> </ul> <p>Other than that, please investigate and fix things that you find. If there are fixes, it's usually to adhere to the rules around processing docstrings, and especially around JSON samples.</p>"},{"location":"UpdateRTD/#checking-for-missing-modules","title":"Checking for missing modules","text":"<p>The file <code>index.rst</code> in the ACA-Py <code>docs</code> folder drive the RTD generation. It picks up all the modules in the source code, starting from the root <code>../aries_cloudagent</code> folder. However, some modules are not picked up automatically from the root and have to be manually added to <code>index.rst</code>. To do that:</p> <ul> <li>Get a list of all generated modules by running: <code>ls generated | grep \"aries_cloudagent.[a-z]*.rst\"</code></li> <li>Compare that list with the modules listed in the \"Subpackages\" section of the left side menu in your browser, including any listed below the \"Submodules\".</li> </ul> <p>If any are missing, you likely need to add them to the <code>index.rst</code> file in the <code>toctree</code> section of the file. You will see there are already several instances of that, notably \"connections\" and \"protocols\".</p>"},{"location":"UpdateRTD/#updating-the-readthedocsorg-site","title":"Updating the readthedocs.org site","text":"<p>The RTD documentation is not currently auto-generated, so a manual re-generation of the documentation is still required.</p> <p>TODO: Automate this when new tags are applied to the repository.</p>"},{"location":"aca-py.org/","title":"Welcome!","text":"<p>Welcome to the Aries Cloud Agent Python documentation site. On this site you will find documentation for recent releases of ACA-Py. You'll find a few of the older versions of ACA-Py (pre-<code>0.8.0</code>), all versions since <code>0.8.0</code>, and the <code>main</code> branch, which is the latest and greatest.</p> <p>All of the documentation here is extracted from the Aries Cloud Agent Python repository. If you want to contribute to the documentation, please start there.</p> <p>Ready to go? Scan the tabs in the page header to find the documentation you need now!</p>"},{"location":"aca-py.org/#code-internals-documentation","title":"Code Internals Documentation","text":"<p>In addition to this documentation site, the ACA-Py community also maintains an ACA-Py internals documentation site. The internals documentation consists of the <code>docstrings</code> extracted from the ACA-Py Python code and covers all of the (non-test) modules in the codebase. Check it out on the Aries Cloud Agent-Python ReadTheDocs site. As with this site, the ReadTheDocs documentation is version specific.</p> <p>Got questions?</p> <ul> <li>Join us on the Hyperledger Discord Server, in the <code>#aries-cloudagent-python</code> channel.</li> <li>Add an issue in the Aries Cloud Agent Python repository.</li> </ul>"},{"location":"assets/","title":"Assets Folder for Documentation","text":"<p>Put any assets (images, source for images, videos, etc.) in this folder to be referenced in the various documents for this repo.</p>"},{"location":"assets/#plantuml-source-and-images","title":"Plantuml Source and Images","text":"<p>Plantuml diagrams are stored in this folder in source form in files ending in <code>.puml</code> and are generated manually using the <code>./genPlantuml</code> script. The script uses a docker image from docker-hub and can be run without downloading any dependencies.</p> <p>If you don't want to use the script, download plantuml and a command line utility and use that for the plantuml generation. I preferred not having any dependencies used (other than docker) and couldn't find a nice way to run plantuml headless from a command line.</p>"},{"location":"assets/#to-do","title":"To Do","text":"<p>It would be better to use a local <code>Dockerfile</code> vs. one found on Docker Hub. The one I did find was simple and straight forward.</p> <p>I couldn't tell if the svg generation was working so just went with png. Not sure which would be better.</p>"},{"location":"demo/","title":"Aries Cloud Agent Python (ACA-Py) Demos","text":"<p>There are several demos available for ACA-Py mostly (but not only) aimed at developers learning how to deploy an instance of the agent and an ACA-Py controller to implement an application.</p>"},{"location":"demo/#table-of-contents","title":"Table of Contents","text":"<ul> <li>The Alice/Faber Python demo</li> <li>Running in a Browser</li> <li>Running in Docker</li> <li>Running Locally<ul> <li>Installing Prerequisites</li> <li>Start a local Indy ledger</li> <li>Genesis File handling</li> <li>Run a local Postgres instance</li> <li>Optional: Run a von-network ledger browser</li> <li>Run the Alice and Faber Controllers/Agents</li> </ul> </li> <li>Follow The Script<ul> <li>Exchanging Messages</li> <li>Issuing and Proving Credentials</li> </ul> </li> <li>Additional Options in the Alice/Faber demo</li> <li>Revocation</li> <li>DID Exchange</li> <li>Endorser</li> <li>Run Indy-SDK Backend</li> <li>Mediation</li> <li>Multi-ledger</li> <li>Multi-tenancy</li> <li>Multi-tenancy with Mediation!!!</li> <li>Other Environment Settings</li> <li>Learning about the Alice/Faber code</li> <li>OpenAPI (Swagger) Demo</li> <li>Performance Demo</li> <li>Coding Challenge: Adding ACME</li> </ul>"},{"location":"demo/#the-alicefaber-python-demo","title":"The Alice/Faber Python demo","text":"<p>The Alice/Faber demo is the (in)famous first verifiable credentials demo. Alice, a former student of Faber College (\"Knowledge is Good\"), connects with the College, is issued a credential about her degree and then is asked by the College for a proof. There are a variety of ways of running the demo. The easiest is in your browser using a site (\"Play with VON\") that let's you run docker containers without installing anything. Alternatively, you can run locally on docker (our recommendation), or using python on your local machine. Each approach is covered below.</p>"},{"location":"demo/#running-in-a-browser","title":"Running in a Browser","text":"<p>In your browser, go to the docker playground service Play with Docker. On the title screen, click \"Start\". On the next screen, click (in the left menu) \"+Add a new instance\".  That will start up a terminal in your browser. Run the following commands to start the Faber agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber\n</code></pre> <p>Now to start Alice's agent. Click the \"+Add a new instance\" button again to open another terminal session. Run the following commands to start Alice's agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice\n</code></pre> <p>Alice's agent is now running.</p> <p>Jump to the Follow the Script section below for further instructions.</p>"},{"location":"demo/#running-in-docker","title":"Running in Docker","text":"<p>Running the demo in docker requires having a <code>von-network</code> (a Hyperledger Indy public ledger sandbox) instance running in docker locally. See the VON Network Tutorial for guidance on starting and stopping your own local Hyperledger Indy instance.</p> <p>Open three <code>bash</code> shells. For Windows users, <code>git-bash</code> is highly recommended. bash is the default shell in Linux and Mac terminal sessions.</p> <p>In the first terminal window, start <code>von-network</code> by following the Building and Starting instructions.</p> <p>In the second terminal, change directory into <code>demo</code> directory of your clone of the Aries Cloud Agent Python repository. Start the <code>faber</code> agent by issuing the following command:</p> <pre><code>  ./run_demo faber\n</code></pre> <p>In the third terminal, change directory into <code>demo</code> directory of your clone of the Aries Cloud Agent Python repository. Start the <code>alice</code> agent by issuing the following command:</p> <pre><code>  ./run_demo alice\n</code></pre> <p>Jump to the Follow the Script section below for further instructions.</p>"},{"location":"demo/#running-locally","title":"Running Locally","text":"<p>The following is an approach to to running the Alice and Faber demo using Python3 running on a bare machine. There are other ways to run the components, but this covers the general approach.</p> <p>We don't recommend this approach if you are just trying this demo, as you will likely run into issues with the specific setup of your machine.</p>"},{"location":"demo/#installing-prerequisites","title":"Installing Prerequisites","text":"<p>We assume you have a running Python 3 environment.  To install the prerequisites specific to running the agent/controller examples in your Python environment, run the following command from this repo's <code>demo</code> folder. The precise command to run may vary based on your Python environment setup.</p> <pre><code>pip3 install -r demo/requirements.txt\n</code></pre> <p>While that process will include the installation of the Indy python prerequisite, you still have to build and install the <code>libindy</code> code for your platform. Follow the installation instructions in the indy-sdk repo for your platform.</p>"},{"location":"demo/#start-a-local-indy-ledger","title":"Start a local Indy ledger","text":"<p>Start a local <code>von-network</code> Hyperledger Indy network running in Docker by following the VON Network Building and Starting instructions.</p> <p>We strongly recommend you use Docker for the local Indy network until you really, really need to know the details of running an Indy Node instance on a bare machine.</p>"},{"location":"demo/#genesis-file-handling","title":"Genesis File handling","text":"<p>Assuming you followed our advice and are using a VON Network instance of Hyperledger Indy, you can ignore this section. If you started the Indy ledger without using VON Network, this information might be helpful.</p> <p>An Aries agent (or other client) connecting to an Indy ledger must know the contents of the <code>genesis</code> file for the ledger. The genesis file lets the agent/client know the IP addresses of the initial nodes of the ledger, and the agent/client sends ledger requests to those IP addresses. When using the <code>indy-sdk</code> ledger, look for the instructions in that repo for how to find/update the ledger genesis file, and note the path to that file on your local system.</p> <p>The envrionment variable <code>GENESIS_FILE</code> is used to let the Aries demo agents know the location of the genesis file. Use the path to that file as value of the <code>GENESIS_FILE</code> environment variable in the instructions below. You might want to copy that file to be local to the demo so the path is shorter.</p>"},{"location":"demo/#run-a-local-postgres-instance","title":"Run a local Postgres instance","text":"<p>The demo uses the postgres database the wallet persistence. Use the Docker Hub certified postgres image to start up a postgres instance to be used for the wallet storage:</p> <pre><code>docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres -c 'log_statement=all' -c 'logging_collector=on' -c 'log_destination=stderr'\n</code></pre>"},{"location":"demo/#optional-run-a-von-network-ledger-browser","title":"Optional: Run a von-network ledger browser","text":"<p>If you followed our advice and are using a VON Network instance of Hyperledger Indy, you can ignore this section, as you already have a Ledger browser running, accessible on http://localhost:9000.</p> <p>If you started the Indy ledger without using VON Network, and you want to be able to browse your local ledger as you run the demo, clone the von-network repo, go into the root of the cloned instance and run the following command, replacing the <code>/path/to/local-genesis.txt</code> with a path to the same genesis file as was used in starting the ledger.</p> <pre><code>GENESIS_FILE=/path/to/local-genesis.txt PORT=9000 REGISTER_NEW_DIDS=true python -m server.server\n</code></pre>"},{"location":"demo/#run-the-alice-and-faber-controllersagents","title":"Run the Alice and Faber Controllers/Agents","text":"<p>With the rest of the pieces running, you can run the Alice and Faber controllers and agents. To do so, <code>cd</code> into the <code>demo</code> folder your clone of this repo in two terminal windows.</p> <p>If you are using a VON Network instance of Hyperledger, run the following commands:</p> <pre><code>DEFAULT_POSTGRES=true python3 -m runners.faber --port 8020\n</code></pre> <pre><code>DEFAULT_POSTGRES=true python3 -m runners.alice --port 8030\n</code></pre> <p>If you started the Indy ledger without using VON Network, use the following commands, replacing the <code>/path/to/local-genesis.txt</code> with the one for your configuration.</p> <pre><code>GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners.faber --port 8020\n</code></pre> <pre><code>GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners.alice --port 8030\n</code></pre> <p>Note that Alice and Faber will each use 5 ports, e.g., using the parameter <code>... --port 8020</code> actually uses ports 8020 through 8024. Feel free to use different ports if you want.</p> <p>Everything running?  See the Follow the Script section below for further instructions.</p> <p>If the demo fails with an error that references the genesis file, a timeout connecting to the Indy Pool, or an Indy <code>307</code> error, it's likely a problem with the genesis file handling. Things to check:</p> <ul> <li>Review the instructions for running the ledger with <code>indy-sdk</code>. Is it running properly?</li> <li>Is the <code>/path/to/local-genesis.txt</code> file correct in your start commands?</li> <li>Look at the IP addresses in the genesis file you are using, and make sure that those IP addresses are accessible from the location you are running the Aries demo</li> <li>Check to make sure that all of the nodes of the ledger started. We've seen examples of only some of the nodes starting up, triggering an Indy <code>307</code> error.</li> </ul>"},{"location":"demo/#follow-the-script","title":"Follow The Script","text":"<p>With both the Alice and Faber agents started, go to the Faber terminal window. The Faber agent has created and displayed an invitation. Copy this invitation and paste it at the Alice prompt. The agents will connect and then show a menu of options:</p> <p>Faber:</p> <pre><code>    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (4) Create New Invitation\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n</code></pre> <p>Alice:</p> <pre><code>    (3) Send Message\n    (4) Input New Invitation\n    (X) Exit?\n</code></pre>"},{"location":"demo/#exchanging-messages","title":"Exchanging Messages","text":"<p>Feel free to use the \"3\" option to send messages back and forth between the agents. Fun, eh? Those are secure, end-to-end encrypted messages.</p>"},{"location":"demo/#issuing-and-proving-credentials","title":"Issuing and Proving Credentials","text":"<p>When ready to test the credentials exchange protocols, go to the Faber prompt, enter \"1\" to send a credential, and then \"2\" to request a proof.</p> <p>You don't need to do anything with Alice's agent - her agent is implemented to automatically receive credentials and respond to proof requests.</p> <p>Note there is an option \"2a\" to initiate a connectionless proof - you can execute this option but it will only work end-to-end when connecting to Faber from a mobile agent.</p>"},{"location":"demo/#additional-options-in-the-alicefaber-demo","title":"Additional Options in the Alice/Faber demo","text":"<p>You can enable support for various ACA-Py features by providing additional command-line arguements when starting up <code>alice</code> or <code>faber</code>.</p> <p>Note that when the controller starts up the agent, it prints out the ACA-Py startup command with all parameters - you can inspect this command to see what parameters are provided in each case.  For more details on the parameters, just start ACA-Py with the <code>--help</code> parameter, for example:</p> <pre><code>./scripts/run_docker start --help\n</code></pre>"},{"location":"demo/#revocation","title":"Revocation","text":"<p>To enable support for revoking credentials, run the <code>faber</code> demo with the <code>--revocation</code> option:</p> <pre><code>./run_demo faber --revocation\n</code></pre> <p>Note that you don't specify this option with <code>alice</code> because it's only applicable for the credential <code>issuer</code> (who has to enable revocation when creating a credential definition, and explicitly revoke credentials as appropriate; alice doesn't have to do anything special when revocation is enabled).</p> <p>You need to run an AnonCreds revocation registry tails server in order to support revocation - the details are described in the Alice gets a Phone demo instructions.</p> <p>Faber will setup support for revocation automatically, and you will see an extra option in faber's menu to revoke a credential:</p> <p><pre><code>    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (4) Create New Invitation\n    (5) Revoke Credential\n    (6) Publish Revocations\n    (7) Rotate Revocation Registry\n    (8) List Revocation Registries\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n  ```\n\nWhen you issue a credential, make a note of the `Revocation registry ID` and `Credential revocation ID`:\n</code></pre> Faber      | Revocation registry ID: WGmUNAdH2ZfeGvacFoMVVP:4:WGmUNAdH2ZfeGvacFoMVVP:3:CL:38:Faber.Agent.degree_schema:CL_ACCUM:15ca49ed-1250-4608-9e8f-c0d52d7260c3 Faber      | Credential revocation ID: 1 <pre><code>When you revoke a credential you will need to provide those values:\n</code></pre> [\u00bd/\u00be/\u215a/\u215e/T/X] 5</p> <p>Enter revocation registry ID: WGmUNAdH2ZfeGvacFoMVVP:4:WGmUNAdH2ZfeGvacFoMVVP:3:CL:38:Faber.Agent.degree_schema:CL_ACCUM:15ca49ed-1250-4608-9e8f-c0d52d7260c3 Enter credential revocation ID: 1 Publish now? [Y/N]: y <pre><code>Note that you need to Publish the revocation information to the ledger.  Once you've revoked a credential any proof which uses this credential will fail to verify.  \n\nRotating the revocation registry will decommission any \"ready\" registry records and create 2 new registry records. You can view in the logs as the records are created and transition to 'active'. There should always be 2 'active' revocation registries - one working and one for hot-swap. Note that revocation information can still be published from decommissioned registries.\n\nYou can also list the created registries, filtering by current state: 'init', 'generated', 'posted', 'active', 'full', 'decommissioned'.\n\n### DID Exchange\n\nYou can enable DID Exchange using the `--did-exchange` parameter for the `alice` and `faber` demos.\n\nThis will use the new DID Exchange protocol when establishing connections between the agents, rather than the older Connection protocol.  There is no other affect on the operation of the agents.\n\nNote that you can't (currently) use the DID Exchange protocol to connect with any of the available mobile agents.\n\n### Endorser\n\nThis is described in [Endorser.md](Endorser.md)\n\n### Run Indy-SDK Backend\n\nThis runs using the older (and not recommended) indy-sdk libraries instead of [Aries Askar](https://github.com/hyperledger/aries-ask):\n\n```bash\n./run_demo faber --wallet-type indy\n</code></pre></p>"},{"location":"demo/#mediation","title":"Mediation","text":"<p>To enable mediation, run the <code>alice</code> or <code>faber</code> demo with the <code>--mediation</code> option:</p> <pre><code>./run_demo faber --mediation\n</code></pre> <p>This will start up a \"mediator\" agent with Alice or Faber and automatically set the alice/faber connection to use the mediator.</p>"},{"location":"demo/#multi-ledger","title":"Multi-ledger","text":"<p>To enable multiple ledger mode, run the <code>alice</code> or <code>faber</code> demo with the <code>--multi-ledger</code> option:</p> <pre><code>./run_demo faber --multi-ledger\n</code></pre> <p>The configuration file for setting up multiple ledgers (for the demo) can be found at <code>./demo/multiple_ledger_config.yml</code>.</p>"},{"location":"demo/#multi-tenancy","title":"Multi-tenancy","text":"<p>To enable support for multi-tenancy, run the <code>alice</code> or <code>faber</code> demo with the <code>--multitenant</code> option:</p> <pre><code>./run_demo faber --multitenant\n</code></pre> <p>(This option can be used with both (or either) <code>alice</code> and/or <code>faber</code>.)</p> <p>You will see an additional menu option to create new sub-wallets (or they can be considered to be \"virtual agents\").</p> <p>Faber:</p> <pre><code>    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (4) Create New Invitation\n    (W) Create and/or Enable Wallet\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n</code></pre> <p>Alice:</p> <pre><code>    (3) Send Message\n    (4) Input New Invitation\n    (W) Create and/or Enable Wallet\n    (X) Exit?\n</code></pre> <p>When you create a new wallet, you just need to provide the wallet name. (If you provide the name of an existing wallet then the controller will \"activate\" that wallet and make it the current wallet.)</p> <pre><code>[1/2/3/4/W/T/X] w\n\nEnter wallet name: new_wallet_12\n\nFaber      | Register or switch to wallet new_wallet_12\nFaber      | Created new profile\nFaber      | Profile backend: indy\nFaber      | Profile name: new_wallet_12\nFaber      | No public DID\n... etc\n</code></pre> <p>Note that <code>faber</code> will create a public DID for this wallet, and will create a schema and credential definition.</p> <p>Once you have created a new wallet, you must establish a connection between <code>alice</code> and <code>faber</code> (remember that this is a new \"virtual agent\" and doesn't know anything about connections established for other \"agents\").</p> <p>In faber, create a new invitation:</p> <pre><code>[1/2/3/4/W/T/X] 4\n\n(... creates a new invitation ...)\n</code></pre> <p>In alice, accept the invitation:</p> <pre><code>[1/2/3/4/W/T/X] 4\n\n(... enter the new invitation string ...)\n</code></pre> <p>You can inspect the additional multi-tenancy admin API's (i.e. the \"agency API\" by opening either agent's swagger page in your browser:</p> Show me a screenshot - multi-tenancy via admin API <p>Note that with multi-tenancy enabled:</p> <ul> <li>The \"base\" wallet will have access to this new \"agency API\" - the agent's admin key, if enabled, must be provided in a header</li> <li>\"Base wallet\" API calls are handled here</li> <li>The \"sub-wallets\" will have access to the \"normal\" ACA-Py admin API - to identify the sub-wallet, a JWT token must be provided, this token is created upon creation of the new wallet (see: this code here)</li> <li>\"Sub-wallet\" API calls are handled here</li> </ul> <p>Documentation on ACA-Py's multi-tenancy support can be found here.</p>"},{"location":"demo/#multi-tenancy-with-mediation","title":"Multi-tenancy with Mediation!!!","text":"<p>There are two options for configuring mediation with multi-tenancy, documented here.</p> <p>This demo implements option #2 - each sub-wallet is configured with a separate connection to the mediator.</p> <p>Run the demo (Alice or Faber) specifying both options:</p> <pre><code>./run_demo faber --multitenant --mediation\n</code></pre> <p>This works exactly as the vanilla multi-tenancy, except that all connections are mediated.</p>"},{"location":"demo/#other-environment-settings","title":"Other Environment Settings","text":"<p>The agents run on a pre-defined set of ports, however occasionally your local system may already be using one of these ports.  (For example MacOS recently decided to use 8021 for the ftp proxy service.)</p> <p>To overriide the default port settings:</p> <pre><code>AGENT_PORT_OVERRIDE=8010 ./run_demo faber\n</code></pre> <p>(The agent requires up to 10 available ports.)</p> <p>To pass extra arguements to the agent (for example):</p> <pre><code>DEMO_EXTRA_AGENT_ARGS=\"[\\\"--emit-did-peer-2\\\"]\" ./run_demo faber --did-exchange --reuse-connections\n</code></pre>"},{"location":"demo/#learning-about-the-alicefaber-code","title":"Learning about the Alice/Faber code","text":"<p>These Alice and Faber scripts (in the <code>demo/runners</code> folder) implement the controller and run the agent as a sub-process (see the documentation for <code>aca-py</code>). The controller publishes a REST service to receive web hook callbacks from their agent. Note that this architecture, running the agent as a sub-process, is a variation on the documented architecture of running the controller and agent as separate processes/containers.</p> <p>The controllers for this demo can be found in the alice.py and faber.py files. Alice and Faber are instances of the agent class found in agent.py.</p>"},{"location":"demo/#openapi-swagger-demo","title":"OpenAPI (Swagger) Demo","text":"<p>Developing an ACA-Py controller is much like developing a web app that uses a REST API. As you develop, you will want an easy way to test out the behaviour of the API. That's where the industry-standard OpenAPI (aka Swagger) UI comes in. ACA-Py (optionally) exposes an OpenAPI UI in ACA-Py that you can use to learn the ins and outs of the API. This Aries OpenAPI demo shows how you can use the OpenAPI UI with an ACA-Py agent by walking through the connectiing, issuing a credential, and presenting a proof sequence.</p>"},{"location":"demo/#performance-demo","title":"Performance Demo","text":"<p>Another example in the <code>demo/runners</code> folder is performance.py, that is used to test out the performance of interacting agents. The script starts up agents for Alice and Faber, initializes them, and then runs through an interaction some number of times. In this case, Faber issues a credential to Alice 300 times.</p> <p>To run the demo, make sure that you shut down any running Alice/Faber agents. Then, follow the same steps to start the Alice/Faber demo, but:</p> <ul> <li>When starting the first agent, replace the agent name (e.g. <code>faber</code>) with <code>performance</code>.</li> <li>Don't start the second agent (<code>alice</code>) at all.</li> </ul> <p>The script starts both agents, runs the performance test, spits out performance results and shuts down the agents. Note that this is just one demonstration of how performance metrics tracking can be done with ACA-Py.</p> <p>A second version of the performance test can be run by adding the parameter <code>--routing</code> to the invocation above. The parameter triggers the example to run with Alice using a routing agent such that all messages pass through the routing agent between Alice and Faber. This is a good, simple example of how routing can be implemented with DIDComm agents.</p> <p>You can also run the demo against a postgres database using the following:</p> <pre><code>./run_demo performance --arg-file demo/postgres-indy-args.yml\n</code></pre> <p>(Obvs you need to be running a postgres database - the command to start postgres is in the yml file provided above.)</p> <p>You can tweak the number of credentials issued using the <code>--count</code> and <code>--batch</code> parameters, and you can run against an Askar database using the <code>--wallet-type askar</code> option (or run using indy-sdk using <code>--wallet-type indy</code>).</p> <p>An example full set of options is:</p> <pre><code>./run_demo performance --arg-file demo/postgres-indy-args.yml -c 10000 -b 10 --wallet-type askar\n</code></pre> <p>Or:</p> <pre><code>./run_demo performance --arg-file demo/postgres-indy-args.yml -c 10000 -b 10 --wallet-type indy\n</code></pre>"},{"location":"demo/#coding-challenge-adding-acme","title":"Coding Challenge: Adding ACME","text":"<p>Now that you have a solid foundation in using ACA-Py, time for a coding challenge. In this challenge, we extend the Alice-Faber command line demo by adding in ACME Corp, a place where Alice wants to work. The demo adds:</p> <ul> <li>ACME inviting Alice to connect</li> <li>ACME requesting a proof of her College degree</li> <li>ACME issuing Alice a credential after she is hired.</li> </ul> <p>The framework for the code is in the acme.py file, but the code is incomplete. Using the knowledge you gained from running demo and viewing the alice.py and faber.py code, fill in the blanks for the code.  When you are ready to test your work:</p> <ul> <li>Use the instructions above to start the Alice/Faber demo (above).</li> <li>Start another terminal session and run the same commands as for \"Alice\", but replace \"alice\" with \"acme\".</li> </ul> <p>All done? Checkout how we added the missing code segments here.</p>"},{"location":"demo/AcmeDemoWorkshop/","title":"Acme Controller Workshop","text":"<p>In this workshop we will add some functionality to a third participant in the Alice/Faber drama - namely, Acme Inc.  After completing her education at Faber College, Alice is going to apply for a job at Acme Inc.  To do this she must provide proof of education (once she has completed the interview and other non-Indy tasks), and then Acme will issue her an employment credential.</p> <p>Note that an updated Acme controller is available here: https://github.com/ianco/aries-cloudagent-python/tree/acme_workshop/demo if you just want to skip ahead ...  There is also an alternate solution with some additional functionality available here:  https://github.com/ianco/aries-cloudagent-python/tree/agent_workshop/demo</p>"},{"location":"demo/AcmeDemoWorkshop/#preview-of-the-acme-controller","title":"Preview of the Acme Controller","text":"<p>There is already a skeleton of the Acme controller in place, you can run it as follows.  (Note that beyond establishing a connection it doesn't actually do anything yet.)</p> <p>To run the Acme controller template, first run Alice and Faber so that Alice can prove her education experience:</p> <p>Open 2 bash shells, and in each run:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>In one shell run Faber:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber\n</code></pre> <p>... and in the second shell run Alice:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice\n</code></pre> <p>When Faber has produced an invitation, copy it over to Alice.</p> <p>Then, in the Faber shell, select option <code>1</code> to issue a credential to Alice.  (You can select option <code>2</code> if you like, to confirm via proof.)</p> <p>Then, in the Faber shell, enter <code>X</code> to exit the controller, and then run the Acme controller:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo acme\n</code></pre> <p>In the Alice shell, select option <code>4</code> (to enter a new invitation) and then copy over Acme's invitation once it's available.</p> <p>Then, in the Acme shell, you can select option <code>2</code> and then option <code>1</code>, which don't do anything ... yet!!!</p>"},{"location":"demo/AcmeDemoWorkshop/#asking-alice-for-a-proof-of-education","title":"Asking Alice for a Proof of Education","text":"<p>In the Acme code <code>acme.py</code> we are going to add code to issue a proof request to Alice, and then validate the received proof.</p> <p>First the following import statements and constants that we will need near the top of acme.py:</p> <pre><code>import random\n\nfrom datetime import date\nfrom uuid import uuid4\n</code></pre> <pre><code>TAILS_FILE_COUNT = int(os.getenv(\"TAILS_FILE_COUNT\", 100))\nCRED_PREVIEW_TYPE = \"https://didcomm.org/issue-credential/2.0/credential-preview\"\n</code></pre> <p>Next locate the code that is triggered by option <code>2</code>:</p> <pre><code>            elif option == \"2\":\n                log_status(\"#20 Request proof of degree from alice\")\n                # TODO presentation requests\n</code></pre> <p>Replace the <code># TODO</code> comment with the following code:</p> <pre><code>                req_attrs = [\n                    {\n                        \"name\": \"name\",\n                        \"restrictions\": [{\"schema_name\": \"degree schema\"}]\n                    },\n                    {\n                        \"name\": \"date\",\n                        \"restrictions\": [{\"schema_name\": \"degree schema\"}]\n                    },\n                    {\n                        \"name\": \"degree\",\n                        \"restrictions\": [{\"schema_name\": \"degree schema\"}]\n                    }\n                ]\n                req_preds = []\n                indy_proof_request = {\n                    \"name\": \"Proof of Education\",\n                    \"version\": \"1.0\",\n                    \"nonce\": str(uuid4().int),\n                    \"requested_attributes\": {\n                        f\"0_{req_attr['name']}_uuid\": req_attr\n                        for req_attr in req_attrs\n                    },\n                    \"requested_predicates\": {}\n                }\n                proof_request_web_request = {\n                    \"connection_id\": agent.connection_id,\n                    \"presentation_request\": {\"indy\": indy_proof_request},\n                }\n                # this sends the request to our agent, which forwards it to Alice\n                # (based on the connection_id)\n                await agent.admin_POST(\n                    \"/present-proof-2.0/send-request\",\n                    proof_request_web_request\n                )\n</code></pre> <p>Now we need to handle receipt of the proof.  Locate the code that handles received proofs (this is in a webhook callback):</p> <pre><code>        if state == \"presentation-received\":\n            # TODO handle received presentations\n            pass\n</code></pre> <p>then replace the <code># TODO</code> comment and the <code>pass</code> statement:</p> <pre><code>            log_status(\"#27 Process the proof provided by X\")\n            log_status(\"#28 Check if proof is valid\")\n            proof = await self.admin_POST(\n                f\"/present-proof-2.0/records/{pres_ex_id}/verify-presentation\"\n            )\n            self.log(\"Proof = \", proof[\"verified\"])\n\n            # if presentation is a degree schema (proof of education),\n            # check values received\n            pres_req = message[\"by_format\"][\"pres_request\"][\"indy\"]\n            pres = message[\"by_format\"][\"pres\"][\"indy\"]\n            is_proof_of_education = (\n                pres_req[\"name\"] == \"Proof of Education\"\n            )\n            if is_proof_of_education:\n                log_status(\"#28.1 Received proof of education, check claims\")\n                for (referent, attr_spec) in pres_req[\"requested_attributes\"].items():\n                    if referent in pres['requested_proof']['revealed_attrs']:\n                        self.log(\n                            f\"{attr_spec['name']}: \"\n                            f\"{pres['requested_proof']['revealed_attrs'][referent]['raw']}\"\n                        )\n                    else:\n                        self.log(\n                            f\"{attr_spec['name']}: \"\n                            \"(attribute not revealed)\"\n                        )\n                for id_spec in pres[\"identifiers\"]:\n                    # just print out the schema/cred def id's of presented claims\n                    self.log(f\"schema_id: {id_spec['schema_id']}\")\n                    self.log(f\"cred_def_id {id_spec['cred_def_id']}\")\n                # TODO placeholder for the next step\n            else:\n                # in case there are any other kinds of proofs received\n                self.log(\"#28.1 Received \", pres_req[\"name\"])\n</code></pre> <p>Right now this just verifies the proof received and prints out the attributes it reveals, but in \"real life\" your application could do something useful with this information.</p> <p>Now you can run the Faber/Alice/Acme script from the \"Preview of the Acme Controller\" section above, and you should see Acme receive a proof from Alice!</p>"},{"location":"demo/AcmeDemoWorkshop/#issuing-alice-a-work-credential","title":"Issuing Alice a Work Credential","text":"<p>Now we can issue a work credential to Alice!</p> <p>There are two options for this.  We can (a) add code under option <code>1</code> to issue the credential, or (b) we can automatically issue this credential on receipt of the education proof.</p> <p>We're going to do option (a), but you can try to implement option (b) as homework.  You have most of the information you need from the proof response!</p> <p>First though we need to register a schema and credential definition.  Find this code:</p> <pre><code>        # acme_schema_name = \"employee id schema\"\n        # acme_schema_attrs = [\"employee_id\", \"name\", \"date\", \"position\"]\n        await acme_agent.initialize(\n            the_agent=agent,\n            # schema_name=acme_schema_name,\n            # schema_attrs=acme_schema_attrs,\n        )\n\n        # TODO publish schema and cred def\n</code></pre> <p>... and uncomment the code lines. Replace the <code># TODO</code> comment with the following code:</p> <pre><code>        with log_timer(\"Publish schema and cred def duration:\"):\n            # define schema\n            version = format(\n                \"%d.%d.%d\"\n                % (\n                    random.randint(1, 101),\n                    random.randint(1, 101),\n                    random.randint(1, 101),\n                )\n            )\n            # register schema and cred def\n            (schema_id, cred_def_id) = await agent.register_schema_and_creddef(\n                \"employee id schema\",\n                version,\n                [\"employee_id\", \"name\", \"date\", \"position\"],\n                support_revocation=False,\n                revocation_registry_size=TAILS_FILE_COUNT,\n            )\n</code></pre> <p>For option (1) we want to replace the <code># TODO</code> comment here:</p> <pre><code>            elif option == \"1\":\n                log_status(\"#13 Issue credential offer to X\")\n                # TODO credential offers\n</code></pre> <p>with the following code:</p> <pre><code>                agent.cred_attrs[cred_def_id] = {\n                    \"employee_id\": \"ACME0009\",\n                    \"name\": \"Alice Smith\",\n                    \"date\": date.isoformat(date.today()),\n                    \"position\": \"CEO\"\n                }\n                cred_preview = {\n                    \"@type\": CRED_PREVIEW_TYPE,\n                    \"attributes\": [\n                        {\"name\": n, \"value\": v}\n                        for (n, v) in agent.cred_attrs[cred_def_id].items()\n                    ],\n                }\n                offer_request = {\n                    \"connection_id\": agent.connection_id,\n                    \"comment\": f\"Offer on cred def id {cred_def_id}\",\n                    \"credential_preview\": cred_preview,\n                    \"filter\": {\"indy\": {\"cred_def_id\": cred_def_id}},\n                }\n                await agent.admin_POST(\n                    \"/issue-credential-2.0/send-offer\", offer_request\n                )\n</code></pre> <p>... and then locate the code that handles the credential request callback:</p> <pre><code>        if state == \"request-received\":\n            # TODO issue credentials based on offer preview in cred ex record\n            pass\n</code></pre> <p>... and replace the <code># TODO</code> comment and <code>pass</code> statement with the following code to issue the credential as Acme offered it:</p> <pre><code>            # issue credentials based on offer preview in cred ex record\n            if not message.get(\"auto_issue\"):\n                await self.admin_POST(\n                    f\"/issue-credential-2.0/records/{cred_ex_id}/issue\",\n                    {\"comment\": f\"Issuing credential, exchange {cred_ex_id}\"},\n                )\n</code></pre> <p>Now you can run the Faber/Alice/Acme steps again.  You should be able to receive a proof and then issue a credential to Alice.</p>"},{"location":"demo/AliceGetsAPhone/","title":"Alice Gets a Mobile Agent!","text":"<p>In this demo, we'll again use our familiar Faber ACA-Py agent to issue credentials to Alice, but this time Alice will use a mobile wallet. To do this we need to run the Faber agent on a publicly accessible port, and Alice will need a compatible mobile wallet. We'll provide pointers to where you can get them.</p> <p>This demo also introduces revocation of credentials.</p>"},{"location":"demo/AliceGetsAPhone/#contents","title":"Contents","text":"<ul> <li>Getting Started</li> <li>Get a mobile agent</li> <li>Running Locally in Docker<ul> <li>Install ngrok and jq</li> <li>Expose services publicly using ngrok</li> </ul> </li> <li>Running in Play With Docker</li> <li>Run an instance of indy-tails-server<ul> <li>Running locally in a bash shell?</li> <li>Running in Play with Docker?</li> </ul> </li> <li>Run <code>faber</code> With Extra Parameters<ul> <li>Running locally in a bash shell?</li> <li>Running in Play with Docker?</li> <li>Waiting for the Faber agent to start ...</li> </ul> </li> <li>Accept the Invitation</li> <li>Issue a Credential</li> <li>Accept the Credential</li> <li>Issue a Presentation Request</li> <li>Present the Proof</li> <li>Review the Proof</li> <li>Revoke the Credential and Send Another Proof Request</li> <li>Send a Connectionless Proof Request</li> <li>Conclusion</li> </ul>"},{"location":"demo/AliceGetsAPhone/#getting-started","title":"Getting Started","text":"<p>This demo can be run on your local machine or on Play with Docker (PWD), and will demonstrate credential exchange and proof exchange as well as revocation with a mobile agent. Both approaches (running locally and on PWD) will be described, for the most part the commands are the same, but there are a couple of different parameters you need to provide when starting up.</p> <p>If you are not familiar with how revocation is currently implemented in Hyperledger Indy, this article provides a good background on the technique. A challenge with revocation as it is currently implemented in Hyperledger Indy is the need for the prover (the agent creating the proof) to download tails files associated with the credentials it holds.</p>"},{"location":"demo/AliceGetsAPhone/#get-a-mobile-agent","title":"Get a mobile agent","text":"<p>Of course for this, you need to have a mobile agent. To find, install and setup a compatible mobile agent, follow the instructions here.</p>"},{"location":"demo/AliceGetsAPhone/#running-locally-in-docker","title":"Running Locally in Docker","text":"<p>Open a new bash shell and in a project directory run the following:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>We'll come back to this in a minute, when we start the <code>faber</code> agent!</p> <p>There are a couple of extra steps you need to take to prepare to run the Faber agent locally:</p>"},{"location":"demo/AliceGetsAPhone/#install-ngrok-and-jq","title":"Install ngrok and jq","text":"<p>ngrok is used to expose public endpoints for services running locally on your computer.</p> <p>jq is a json parser that is used to automatically detect the endpoints exposed by ngrok.</p> <p>You can install ngrok from here</p> <p>You can download jq releases here</p>"},{"location":"demo/AliceGetsAPhone/#expose-services-publicly-using-ngrok","title":"Expose services publicly using ngrok","text":"<p>Note that this is only required when running docker on your local machine. When you run on PWD a public endpoint for your agent is exposed automatically.</p> <p>Since the mobile agent will need some way to communicate with the agent running on your local machine in docker, we will need to create a publicly accesible url for some services on your machine. The easiest way to do this is with ngrok. Once ngrok is installed, create a tunnel to your local machine:</p> <pre><code>ngrok http 8020\n</code></pre> <p>This service is used for your local aca-py agent - it is the endpoint that is advertised for other Aries agents to connect to.</p> <p>You will see something like this:</p> <pre><code>Forwarding                    http://abc123.ngrok.io -&gt; http://localhost:8020\nForwarding                    https://abc123.ngrok.io -&gt; http://localhost:8020\n</code></pre> <p>This creates a public url for ports 8020 on your local machine.</p> <p>Note that an ngrok process is created automatically for your tails server.</p> <p>Keep this process running as we'll come back to it in a moment.</p>"},{"location":"demo/AliceGetsAPhone/#running-in-play-with-docker","title":"Running in Play With Docker","text":"<p>To run the necessary terminal sessions in your browser, go to the Docker playground service Play with Docker. Don't know about Play with Docker? Check this out to learn more.</p> <p>Open a new bash shell and in a project directory run the following:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>We'll come back to this in a minute, when we start the <code>faber</code> agent!</p>"},{"location":"demo/AliceGetsAPhone/#run-an-instance-of-indy-tails-server","title":"Run an instance of indy-tails-server","text":"<p>For revocation to function, we need another component running that is used to store what are called tails files.</p> <p>If you are not running with revocation enabled you can skip this step.</p>"},{"location":"demo/AliceGetsAPhone/#running-locally-in-a-bash-shell","title":"Running locally in a bash shell?","text":"<p>Open a new bash shell, and in a project directory, run:</p> <pre><code>git clone https://github.com/bcgov/indy-tails-server.git\ncd indy-tails-server/docker\n./manage build\n./manage start\n</code></pre> <p>This will run the required components for the tails server to function and make a tails server available on port 6543.</p> <p>This will also automatically start an ngrok server that will expose a public url for your tails server - this is required to support mobile agents. The docker output will look something like this:</p> <pre><code>ngrok-tails-server_1  | t=2020-05-13T22:51:14+0000 lvl=info msg=\"started tunnel\" obj=tunnels name=\"command_line (http)\" addr=http://tails-server:6543 url=http://c5789aa0.ngrok.io\nngrok-tails-server_1  | t=2020-05-13T22:51:14+0000 lvl=info msg=\"started tunnel\" obj=tunnels name=command_line addr=http://tails-server:6543 url=https://c5789aa0.ngrok.io\n</code></pre> <p>Note the server name in the <code>url=https://c5789aa0.ngrok.io</code> parameter (<code>https://c5789aa0.ngrok.io</code>) - this is the external url for your tails server. Make sure you use the <code>https</code> url!</p>"},{"location":"demo/AliceGetsAPhone/#running-in-play-with-docker_1","title":"Running in Play with Docker?","text":"<p>Run the same steps on PWD as you would run locally (see above).  Open a new shell (click on \"ADD NEW INSTANCE\") to run the tails server.</p> <p>Note that with Play with Docker it can be challenging to capture the information you need from the log file as it scrolls by, you can try leaving off the <code>--events</code> option when you run the Faber agent to reduce the quantity of information logged to the screen.</p>"},{"location":"demo/AliceGetsAPhone/#run-faber-with-extra-parameters","title":"Run <code>faber</code> With Extra Parameters","text":""},{"location":"demo/AliceGetsAPhone/#running-locally-in-a-bash-shell_1","title":"Running locally in a bash shell?","text":"<p>If you are running in a local bash shell, navigate to the <code>demo</code> directory in your fork/clone of the Aries Cloud Agent Python repository and run:</p> <pre><code>TAILS_NETWORK=docker_tails-server LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --aip 10 --revocation --events\n</code></pre> <p>(Note that we have to start faber with <code>--aip 10</code> for compatibility with mobile clients.)</p> <p>The <code>TAILS_NETWORK</code> parameter lets the demo script know how to connect to the tails server (which should be running in a separate shell on the same machine).</p>"},{"location":"demo/AliceGetsAPhone/#running-in-play-with-docker_2","title":"Running in Play with Docker?","text":"<p>If you are running in Play with Docker, navigate to the <code>demo</code> folder in the clone of Aries Cloud Agent Python and run the following:</p> <pre><code>PUBLIC_TAILS_URL=https://c4f7fbb85911.ngrok.io LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --aip 10 --revocation --events\n</code></pre> <p>The <code>PUBLIC_TAILS_URL</code> parameter lets the demo script know how to connect to the tails server. This can be running in another PWD session, or even on your local machine - the ngrok endpoint is public and will map to the correct location.</p> <p>Use the ngrok url for the tails server that you noted earlier.</p> <p>*Note that you must use the <code>https</code> url for the tails server endpoint.</p> <p>*Note - you may want to leave off the <code>--events</code> option when you run the Faber agent, if you are finding you are getting too much logging output.</p>"},{"location":"demo/AliceGetsAPhone/#waiting-for-the-faber-agent-to-start","title":"Waiting for the Faber agent to start ...","text":"<p>The <code>Preparing agent image...</code> step on the first run takes a bit of time, so while we wait, let's look at the details of the commands. Running Faber is similar to the instructions in the Aries OpenAPI Demo \"Play with Docker\" section, except:</p> <ul> <li>We are using the BCovrin Test network because that is a network that the mobile agents can be configured to use.</li> <li>We are running in \"auto\" mode, so we will make no manual acknowledgements.</li> <li>The revocation related changes:</li> <li>The <code>TAILS_NETWORK</code> parameter tells the <code>./run_demo</code> script how to connect to the tails server and determine the public ngrok endpoint.</li> <li>The <code>PUBLIC_TAILS_URL</code> environment variable is the address of your tails server (must be <code>https</code>).</li> <li>The <code>--revocation</code> parameter to the <code>./run-demo</code> script activates the ACA-Py revocation issuance.</li> </ul> <p>As part of its startup process, the agent will publish a revocation registry to the ledger.</p> Click here to view screenshot of the revocation registry on the ledger"},{"location":"demo/AliceGetsAPhone/#accept-the-invitation","title":"Accept the Invitation","text":"<p>When the Faber agent starts up it automatically creates an invitation and generates a QR code on the screen. On your mobile app, select \"SCAN CODE\" (or equivalent) and point your camera at the generated QR code. The mobile agent should automatically capture the code and ask you to confirm the connection. Confirm it.</p> Click here to view screenshot <p>The mobile agent will give you feedback on the connection process, something like \"A connection was added to your wallet\".</p> Click here to view screenshot Click here to view screenshot <p>Switch your browser back to Play with Docker. You should see that the connection has been established, and there is a prompt for what actions you want to take, e.g. \"Issue Credential\", \"Send Proof Request\" and so on.</p> <p>Tip: If your screen is too small to display the QR code (this can happen in Play With Docker because the shell is only given a small portion of the browser) you can copy the invitation url to a site like https://www.the-qrcode-generator.com/ to convert the invitation url into a QR code that you can scan. Make sure you select the <code>URL</code> option, and copy the <code>invitation_url</code>, which will look something like:</p> <pre><code>https://abfde260.ngrok.io?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiZjI2ZjA2YTItNWU1Mi00YTA5LWEwMDctOTNkODBiZTYyNGJlIiwgInJlY2lwaWVudEtleXMiOiBbIjlQRFE2alNXMWZwZkM5UllRWGhCc3ZBaVJrQmVKRlVhVmI0QnRQSFdWbTFXIl0sICJsYWJlbCI6ICJGYWJlci5BZ2VudCIsICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cHM6Ly9hYmZkZTI2MC5uZ3Jvay5pbyJ9\n</code></pre> <p>Or this:</p> <pre><code>http://ip10-0-121-4-bquqo816b480a4bfn3kg-8020.direct.play-with-docker.com?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiZWI2MTI4NDUtYmU1OC00YTNiLTk2MGUtZmE3NDUzMGEwNzkyIiwgInJlY2lwaWVudEtleXMiOiBbIkFacEdoMlpIOTJVNnRFRTlmYk13Z3BqQkp3TEUzRFJIY1dCbmg4Y2FqdzNiIl0sICJzZXJ2aWNlRW5kcG9pbnQiOiAiaHR0cDovL2lwMTAtMC0xMjEtNC1icXVxbzgxNmI0ODBhNGJmbjNrZy04MDIwLmRpcmVjdC5wbGF5LXdpdGgtdm9uLnZvbnguaW8iLCAibGFiZWwiOiAiRmFiZXIuQWdlbnQifQ==\n</code></pre> <p>Note that this will use the ngrok endpoint if you are running locally, or your PWD endpoint if you are running on PWD.</p>"},{"location":"demo/AliceGetsAPhone/#issue-a-credential","title":"Issue a Credential","text":"<p>We will use the Faber console to issue a credential. This could be done using the Swagger API as we have done in the connection process. We'll leave that as an exercise to the user.</p> <p>In the Faber console, select option <code>1</code> to send a credential to the mobile agent.</p> Click here to view screenshot <p>The Faber agent outputs details to the console; e.g.,</p> <pre><code>Faber      | Credential: state = credential-issued, cred_ex_id = ba3089d6-92da-4cb7-9062-7f24066b2a2a\nFaber      | Revocation registry ID: CMqNjZ8e59jDuBYcquce4D:4:CMqNjZ8e59jDuBYcquce4D:3:CL:50:faber.agent.degree_schema:CL_ACCUM:4f4fb2e4-3a59-45b1-8921-578d005a7ff6\nFaber      | Credential revocation ID: 1\nFaber      | Credential: state = done, cred_ex_id = ba3089d6-92da-4cb7-9062-7f24066b2a2a\n</code></pre> <p>The revocation registry id and credential revocation id only appear if revocation is active. If you are doing revocation, you to need the <code>Revocation registry id</code> later, so we recommend that you copy it it now and paste it into a text file or someplace that you can access later. If you don't write it down, you can get the Id from the Admin API using the <code>GET /revocation/active-registry/{cred_def_id}</code> endpoint, and passing in the credential definition Id (which you can get from the <code>GET /credential-definitions/created</code> endpoint).</p>"},{"location":"demo/AliceGetsAPhone/#accept-the-credential","title":"Accept the Credential","text":"<p>The credential offer should automatically show up in the mobile agent. Accept the offered credential following the instructions provided by the mobile agent. That will look something like this:</p> Click here to view screenshot Click here to view screenshot Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#issue-a-presentation-request","title":"Issue a Presentation Request","text":"<p>We will use the Faber console to ask mobile agent for a proof. This could be done using the Swagger API, but we'll leave that as an exercise to the user.</p> <p>In the Faber console, select option <code>2</code> to send a proof request to the mobile agent.</p> Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#present-the-proof","title":"Present the Proof","text":"<p>The presentation (proof) request should automatically show up in the mobile agent. Follow the instructions provided by the mobile agent to prepare and send the proof back to Faber. That will look something like this:</p> Click here to view screenshot Click here to view screenshot Click here to view screenshot <p>If the mobile agent is able to successfully prepare and send the proof, you can go back to the Play with Docker terminal to see the status of the proof.</p> <p>The process should \"just work\" for the non-revocation use case. If you are using revocation, your results may vary. As of writing this, we get failures on the wallet side with some mobile wallets, and on the Faber side with others (an error in the Indy SDK). As the results improve, we'll update this. Please let us know through GitHub issues if you have any problems running this.</p>"},{"location":"demo/AliceGetsAPhone/#review-the-proof","title":"Review the Proof","text":"<p>In the Faber console window, the proof should be received as validated.</p> Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#revoke-the-credential-and-send-another-proof-request","title":"Revoke the Credential and Send Another Proof Request","text":"<p>If you have enabled revocation, you can try revoking the credential and publishing its pending revoked status (<code>faber</code> options <code>5</code> and <code>6</code>). For the revocation step, You will need the revocation registry identifier and the credential revocation identifier (which is 1 for the first credential you issued), as the Faber agent logged them to the console at credential issue.</p> <p>Once that is done, try sending another proof request and see what happens! Experiment with immediate and pending publication. Note that immediate publication also publishes any pending revocations on its revocation registry.</p> Click here to view screenshot"},{"location":"demo/AliceGetsAPhone/#send-a-connectionless-proof-request","title":"Send a Connectionless Proof Request","text":"<p>A connectionless proof request works the same way as a regular proof request, however it does not require a connection to be established between the Verifier and Holder/Prover.</p> <p>This is supported in the Faber demo, however note that it will only work when running Faber on the Docker playground service Play with Docker.  (This is because both the Faber agent and controller both need to be exposed to the mobile agent.)</p> <p>If you have gone through the above steps, you can delete the Faber connection in your mobile agent (however do not delete the credential that Faber issued to you).</p> <p>Then in the faber demo, select option <code>2a</code> - Faber will display a QR code which you can scan with your mobile agent.  You will see the same proof request displayed in your mobile agent, which you can respond to.</p> <p>Behind the scenes, the Faber controller delivers the proof request information (linked from the url encoded in the QR code) directly to your mobile agent, without establishing and agent-to-agent connection first.  If you are interested in the underlying mechanics, you can review the <code>faber.py</code> code in the repository.</p>"},{"location":"demo/AliceGetsAPhone/#conclusion","title":"Conclusion","text":"<p>That\u2019s the Faber-Mobile Alice demo. Feel free to play with the Swagger API and experiment further and figure out what an instance of a controller has to do to make things work.</p>"},{"location":"demo/AliceWantsAJsonCredential/","title":"How to Issue JSON-LD Credentials using ACA-Py","text":"<p>ACA-Py has the capability to issue and verify both Indy and JSON-LD (W3C compliant) credentials.</p> <p>The JSON-LD support is documented here - this document will provide some additional detail in how to use the demo and admin api to issue and prove JSON-LD credentials.</p>"},{"location":"demo/AliceWantsAJsonCredential/#setup-agents-to-issue-json-ld-credentials","title":"Setup Agents to Issue JSON-LD Credentials","text":"<p>Clone this repository to a directory on your local:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python.git\ncd aries-cloudagent-python/demo\n</code></pre> <p>Open up a second shell (so you have 2 shells open in the <code>demo</code> directory) and in one shell:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --did-exchange --aip 20 --cred-type json-ld\n</code></pre> <p>... and in the other:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice\n</code></pre> <p>Note that you start the <code>faber</code> agent with AIP2.0 options.  (When you specify <code>--cred-type json-ld</code> faber will set aip to <code>20</code> automatically, so the <code>--aip</code> option is not strictly required). Note as well the use of the <code>LEDGER_URL</code>. Technically, that should not be needed if we aren't doing anything with an Indy ledger-based credentials. However, there must be something in the way that the Faber and Alice controllers are starting up that requires access to a ledger.</p> <p>Also note that the above will only work with the <code>/issue-credential-2.0/create-offer</code> endpoint.  If you want to use the <code>/issue-credential-2.0/send</code> endpoint - which automates each step of the credential exchange - you will need to include the <code>--no-auto</code> option when starting each of the alice and faber agents (since the alice and faber controllers also automatically respond to each step in the credential exchange).</p> <p>(Alternately you can run run Alice and Faber agents locally, see the <code>./faber-local.sh</code> and <code>./alice-local.sh</code> scripts in the <code>demo</code> directory.)</p> <p>Copy the \"invitation\" json text from the Faber shell and paste into the Alice shell to establish a connection between the two agents.</p> <p>(If you are running with <code>--no-auto</code> you will also need to call the <code>/connections/{conn_id}/accept-invitation</code> endpoint in alice's admin api swagger page.)</p> <p>Now open up two browser windows to the Faber and Alice admin api swagger pages.</p> <p>Using the Faber admin api, you have to create a DID with the appropriate:</p> <ul> <li>DID method (\"key\" or \"sov\")</li> <li>key type \"ed25519\" or \"bls12381g2\" (corresponding to signature types \"Ed25519Signature2018\" or \"BbsBlsSignature2020\")</li> <li>if you use DID method \"sov\" you must use key type \"ed25519\"</li> </ul> <p>Note that \"did:sov\" must be a public DID (i.e. registered on the ledger) but \"did:key\" is not.</p> <p>For example, in Faber's swagger page call the <code>/wallet/did/create</code> endpoint with the following payload:</p> <pre><code>{\n  \"method\": \"key\",\n  \"options\": {\n    \"key_type\": \"bls12381g2\" // or ed25519\n  }\n}\n</code></pre> <p>This will return something like:</p> <pre><code>{\n  \"result\": {\n    \"did\": \"did:key:zUC71KdwBhq1FioWh53VXmyFiGpewNcg8Ld42WrSChpMzzskRWwHZfG9TJ7hPj8wzmKNrek3rW4ZkXNiHAjVchSmTr9aNUQaArK3KSkTySzjEM73FuDV62bjdAHF7EMnZ27poCE\",\n    \"verkey\": \"mV6482Amu6wJH8NeMqH3QyTjh6JU6N58A8GcirMZG7Wx1uyerzrzerA2EjnhUTmjiSLAp6CkNdpkLJ1NTS73dtcra8WUDDBZ3o455EMrkPyAtzst16RdTMsGe3ctyTxxJav\",\n    \"posture\": \"wallet_only\",\n    \"key_type\": \"bls12381g2\",\n    \"method\": \"key\"\n  }\n}\n</code></pre> <p>You do not create a schema or cred def for a JSON-LD credential (these are only required for \"indy\" credentials).</p> <p>You will need to create a DID as above for Alice as well (<code>/wallet/did/create</code> etc ...).</p> <p>Congratulations, you are now ready to start issuing JSON-LD credentials!</p> <ul> <li>You have two agents with a connection established between the agents - you will need to copy Faber's <code>connection_id</code> into the examples below.</li> <li>You have created a (non-public) DID for Faber to use to sign/issue the credentials - you will need to copy the DID that you created above into the examples below (as <code>issuer</code>).</li> <li>You have created a (non-public) DID for Alice to use as her <code>credentialSubject.id</code> - this is required for Alice to sign the proof (the <code>credentialSubject.id</code> is not required, but then the provided presentation can't be verified).</li> </ul> <p>To issue a credential, use the <code>/issue-credential-2.0/send-offer</code> endpoint. (You can also use the <code>/issue-credential-2.0/send</code>) endpoint, if, as mentioned above, you have included the <code>--no-auto</code> when starting both of the agents.)</p> <p>You can test with this example payload (just replace the \"connection_id\", \"issuer\" key, \"credentialSubject.id\" and \"proofType\" with appropriate values:</p> <pre><code>{\n  \"connection_id\": \"4fba2ce5-b411-4ecf-aa1b-ec66f3f6c903\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"UniversityDegreeCredential\"],\n        \"issuer\": \"did:key:zUC71KdwBhq1FioWh53VXmyFiGpewNcg8Ld42WrSChpMzzskRWwHZfG9TJ7hPj8wzmKNrek3rW4ZkXNiHAjVchSmTr9aNUQaArK3KSkTySzjEM73FuDV62bjdAHF7EMnZ27poCE\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"givenName\": \"Sally\",\n          \"familyName\": \"Student\",\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"degreeType\": \"Undergraduate\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre> <p>Note that if you have the \"auto\" settings on, this is all you need to do.  Otherwise you need to call the <code>/send-request</code>, <code>/store</code>, etc endpoints to complete the protocol.</p> <p>To see the issued credential, call the <code>/credentials/w3c</code> endpoint on Alice's admin api - this will return something like:</p> <pre><code>{\n  \"results\": [\n    {\n      \"contexts\": [\n        \"https://w3id.org/security/bbs/v1\",\n        \"https://www.w3.org/2018/credentials/examples/v1\",\n        \"https://www.w3.org/2018/credentials/v1\"\n      ],\n      \"types\": [\n        \"UniversityDegreeCredential\",\n        \"VerifiableCredential\"\n      ],\n      \"schema_ids\": [],\n      \"issuer_id\": \"did:key:zUC71KdwBhq1FioWh53VXmyFiGpewNcg8Ld42WrSChpMzzskRWwHZfG9TJ7hPj8wzmKNrek3rW4ZkXNiHAjVchSmTr9aNUQaArK3KSkTySzjEM73FuDV62bjdAHF7EMnZ27poCE\",\n      \"subject_ids\": [],\n      \"proof_types\": [\n        \"BbsBlsSignature2020\"\n      ],\n      \"cred_value\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\",\n          \"https://w3id.org/security/bbs/v1\"\n        ],\n        \"type\": [\n          \"VerifiableCredential\",\n          \"UniversityDegreeCredential\"\n        ],\n        \"issuer\": \"did:key:zUC71Kd...poCE\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"givenName\": \"Sally\",\n          \"familyName\": \"Student\",\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"degreeType\": \"Undergraduate\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        },\n        \"proof\": {\n          \"type\": \"BbsBlsSignature2020\",\n          \"proofPurpose\": \"assertionMethod\",\n          \"verificationMethod\": \"did:key:zUC71Kd...poCE#zUC71Kd...poCE\",\n          \"created\": \"2021-05-19T16:19:44.458170\",\n          \"proofValue\": \"g0weLyw2Q+niQ4pGfiXB...tL9C9ORhy9Q==\"\n        }\n      },\n      \"cred_tags\": {},\n      \"record_id\": \"365ab87b12f74b2db784fdd4db8419f5\"\n    }\n  ]\n}\n</code></pre> <p>If you don't see the credential in your wallet, look up the credential exchange record (in alice's admin api - <code>/issue-credential-2.0/records</code>) and check the state.  If the state is <code>credential-received</code>, then the credential has been received but not stored, in this case just call the <code>/store</code> endpoint for this credential exchange.</p>"},{"location":"demo/AliceWantsAJsonCredential/#building-more-realistic-json-ld-credentials","title":"Building More Realistic JSON-LD Credentials","text":"<p>The above example uses the <code>https://www.w3.org/2018/credentials/examples/v1</code> context, which should never be used in a real application.</p> <p>To build credentials in real life, you first determine which attributes you need and then include the appropriate contexts.</p>"},{"location":"demo/AliceWantsAJsonCredential/#context-schemaorg","title":"Context schema.org","text":"<p>You can use attributes defined on schema.org.  Although this is NOT RECOMMENDED (included here for illustrative purposes only) - individual attributes can't be validated (see the comment later on).</p> <p>You first include <code>https://schema.org</code> in the <code>@context</code> block of the credential as follows:</p> <pre><code>\"@context\": [\n  \"https://www.w3.org/2018/credentials/v1\",\n  \"https://schema.org\"\n],\n</code></pre> <p>Then you review the attributes and objects defined by <code>https://schema.org</code> and decide what you need to include in your credential.</p> <p>For example to issue a credetial with givenName, familyName and alumniOf attributes, submit the following:</p> <pre><code>{\n  \"connection_id\": \"ad35a4d8-c84b-4a4f-a83f-1afbf134b8b9\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://schema.org\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"Person\"],\n        \"issuer\": \"did:key:zUC71pj2gpDLfcZ9DE1bMtjZGWCSLhkQsUCaKjqXtCftGkz27894pEX9VvGNiFsaV67gqv2TEPQ2aDaDDdTDNp42LfDdK1LaWSBCfzsQEyaiR1zjZm1RtoRu1ZM6v6vz4TiqDgU\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"givenName\": \"Sally\",\n          \"familyName\": \"Student\",\n          \"alumniOf\": \"Example University\"\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre> <p>Note that with <code>https://schema.org</code>, if you include attributes that aren't defined by any context, you will not get an error.  For example you can try replacing the <code>credentialSubject</code> in the above with:</p> <pre><code>\"credentialSubject\": {\n  \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n  \"givenName\": \"Sally\",\n  \"familyName\": \"Student\",\n  \"alumniOf\": \"Example University\",\n  \"someUndefinedAttribute\": \"the value of the attribute\"\n}\n</code></pre> <p>... and the credential issuance should fail, however <code>https://schema.org</code> defines a <code>@vocab</code> that by default all terms derive from (see here).</p> <p>You can include more complex schemas, for example to use the schema.org Person schema (which includes <code>givenName</code> and <code>familyName</code>):</p> <pre><code>{\n  \"connection_id\": \"ad35a4d8-c84b-4a4f-a83f-1afbf134b8b9\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://schema.org\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"Person\"],\n        \"issuer\": \"did:key:zUC71pj2gpDLfcZ9DE1bMtjZGWCSLhkQsUCaKjqXtCftGkz27894pEX9VvGNiFsaV67gqv2TEPQ2aDaDDdTDNp42LfDdK1LaWSBCfzsQEyaiR1zjZm1RtoRu1ZM6v6vz4TiqDgU\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n          \"student\": {\n            \"type\": \"Person\",\n            \"givenName\": \"Sally\",\n            \"familyName\": \"Student\",\n            \"alumniOf\": \"Example University\"\n          }\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"demo/AliceWantsAJsonCredential/#credential-specific-contexts","title":"Credential-Specific Contexts","text":"<p>The recommended approach to defining credentials is to define a credential-specific vocabulary (or make use of existing ones).  (Note that these can include references to <code>https://schema.org</code>, you just shouldn't uste this directly in your credential.)</p>"},{"location":"demo/AliceWantsAJsonCredential/#credential-issue-example","title":"Credential Issue Example","text":"<p>The following example uses the W3C citizenship context to issue a PermanentResident credential (replace the <code>connection_id</code>, <code>issuer</code> and <code>credentialSubject.id</code> with your local values):</p> <pre><code>{\n    \"connection_id\": \"41acd909-9f45-4c69-8641-8146e0444a57\",\n    \"filter\": {\n        \"ld_proof\": {\n            \"credential\": {\n                \"@context\": [\n                    \"https://www.w3.org/2018/credentials/v1\",\n                    \"https://w3id.org/citizenship/v1\"\n                ],\n                \"type\": [\n                    \"VerifiableCredential\",\n                    \"PermanentResident\"\n                ],\n                \"id\": \"https://credential.example.com/residents/1234567890\",\n                \"issuer\": \"did:key:zUC7Dus47jW5Avcne8LLsUvJSdwspmErgehxMWqZZy8eSSNoHZ4x8wgs77sAmQtCADED5RQP1WWhvt7KFNm6GGMxdSGpKu3PX6R9a61G9VoVsiFoRf1yoK6pzhq9jtFP3e2SmU9\",\n                \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n                \"credentialSubject\": {\n                    \"type\": [\n                        \"PermanentResident\"\n                    ],\n                    \"id\": \"did:key:zUC7CXi82AXbkv4SvhxDxoufrLwQSAo79qbKiw7omCQ3c4TyciDdb9s3GTCbMvsDruSLZX6HNsjGxAr2SMLCNCCBRN5scukiZ4JV9FDPg5gccdqE9nfCU2zUcdyqRiUVnn9ZH83\",\n                    \"givenName\": \"ALICE\",\n                    \"familyName\": \"SMITH\",\n                    \"gender\": \"Female\",\n                    \"birthCountry\": \"Bahamas\",\n                    \"birthDate\": \"1958-07-17\"\n                }\n            },\n            \"options\": {\n                \"proofType\": \"BbsBlsSignature2020\"\n            }\n        }\n    }\n}\n</code></pre> <p>Copy and paste this content into Faber's <code>/issue-credential-2.0/send-offer</code> endpoint, and it will kick off the exchange process to issue a W3C credential to Alice.</p> <p>In Alice's swagger page, submit the <code>/credentials/records/w3c</code> endpoint to see the issued credential.</p>"},{"location":"demo/AliceWantsAJsonCredential/#request-presentation-example","title":"Request Presentation Example","text":"<p>To request a proof, submit the following (with appropriate <code>connection_id</code>) to Faber's <code>/present-proof-2.0/send-request</code> endpoint:</p> <pre><code>{\n    \"comment\": \"string\",\n    \"connection_id\": \"41acd909-9f45-4c69-8641-8146e0444a57\",\n    \"presentation_request\": {\n        \"dif\": {\n            \"options\": {\n                \"challenge\": \"3fa85f64-5717-4562-b3fc-2c963f66afa7\",\n                \"domain\": \"4jt78h47fh47\"\n            },\n            \"presentation_definition\": {\n                \"id\": \"32f54163-7166-48f1-93d8-ff217bdb0654\",\n                \"format\": {\n                    \"ldp_vp\": {\n                        \"proof_type\": [\n                            \"BbsBlsSignature2020\"\n                        ]\n                    }\n                },\n                \"input_descriptors\": [\n                    {\n                        \"id\": \"citizenship_input_1\",\n                        \"name\": \"EU Driver's License\",\n                        \"schema\": [\n                            {\n                                \"uri\": \"https://www.w3.org/2018/credentials#VerifiableCredential\"\n                            },\n                            {\n                                \"uri\": \"https://w3id.org/citizenship#PermanentResident\"\n                            }\n                        ],\n                        \"constraints\": {\n                            \"limit_disclosure\": \"required\",\n                            \"is_holder\": [\n                                {\n                                    \"directive\": \"required\",\n                                    \"field_id\": [\n                                        \"1f44d55f-f161-4938-a659-f8026467f126\"\n                                    ]\n                                }\n                            ],\n                            \"fields\": [\n                                {\n                                    \"id\": \"1f44d55f-f161-4938-a659-f8026467f126\",\n                                    \"path\": [\n                                        \"$.credentialSubject.familyName\"\n                                    ],\n                                    \"purpose\": \"The claim must be from one of the specified issuers\",\n                                    \"filter\": {\n                                        \"const\": \"SMITH\"\n                                    }\n                                },\n                                {\n                                    \"path\": [\n                                        \"$.credentialSubject.givenName\"\n                                    ],\n                                    \"purpose\": \"The claim must be from one of the specified issuers\"\n                                }\n                            ]\n                        }\n                    }\n                ]\n            }\n        }\n    }\n}\n</code></pre> <p>Note that the <code>is_holder</code> property can be used by Faber to verify that the holder of credential is the same as the subject of the attribute (<code>familyName</code>). Later on, the received presentation will be signed and verifiable only if <code>is_holder</code> with <code>\"directive\": \"required\"</code> is included in the presentation request.</p> <p>There are several ways that Alice can respond with a presentation.  The simplest will just tell ACA-Py to put the presentation together and send it to Faber - submit the following to Alice's <code>/present-proof-2.0/records/{pres_ex_id}/send-presentation</code>:</p> <pre><code>{\n  \"dif\": {\n  }\n}\n</code></pre> <p>There are two ways that Alice can provide some constraints to tell ACA-Py which credential(s) to include in the presentation.</p> <p>Firstly, Alice can include the received presentation request in the body to the <code>/send-presentation</code> endpoint, and can include additional constraints on the fields:</p> <pre><code>{\n  \"dif\": {\n    \"issuer_id\": \"did:key:zUC7Dus47jW5Avcne8LLsUvJSdwspmErgehxMWqZZy8eSSNoHZ4x8wgs77sAmQtCADED5RQP1WWhvt7KFNm6GGMxdSGpKu3PX6R9a61G9VoVsiFoRf1yoK6pzhq9jtFP3e2SmU9\",\n    \"presentation_definition\": {\n      \"format\": {\n        \"ldp_vp\": {\n          \"proof_type\": [\n            \"BbsBlsSignature2020\"\n          ]\n        }\n      },\n      \"id\": \"32f54163-7166-48f1-93d8-ff217bdb0654\",\n      \"input_descriptors\": [\n        {\n          \"id\": \"citizenship_input_1\",\n          \"name\": \"Some kind of citizenship check\",\n          \"schema\": [\n            {\n              \"uri\": \"https://www.w3.org/2018/credentials#VerifiableCredential\"\n            },\n            {\n              \"uri\": \"https://w3id.org/citizenship#PermanentResident\"\n            }\n          ],\n          \"constraints\": {\n            \"limit_disclosure\": \"required\",\n            \"is_holder\": [\n                {\n                    \"directive\": \"required\",\n                    \"field_id\": [\n                        \"1f44d55f-f161-4938-a659-f8026467f126\",\n                        \"332be361-823a-4863-b18b-c3b930c5623e\"\n                    ],\n                }\n            ],\n            \"fields\": [\n              {\n                \"id\": \"1f44d55f-f161-4938-a659-f8026467f126\",\n                \"path\": [\n                  \"$.credentialSubject.familyName\"\n                ],\n                \"purpose\": \"The claim must be from one of the specified issuers\",\n                \"filter\": {\n                  \"const\": \"SMITH\"\n                }\n              },\n              {\n                  \"id\": \"332be361-823a-4863-b18b-c3b930c5623e\",\n                  \"path\": [\n                      \"$.id\"\n                  ],\n                  \"purpose\": \"Specify the id of the credential to present\",\n                  \"filter\": {\n                      \"const\": \"https://credential.example.com/residents/1234567890\"\n                  }\n              }\n            ]\n          }\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>Note the additional constraint on <code>\"path\": [ \"$.id\" ]</code> - this restricts the presented credential to the one with the matching <code>credential.id</code>.  Any credential attributes can be used, however this presumes that the issued credentials contain a uniquely identifying attribute.</p> <p>Another option is for Alice to specify the credential <code>record_id</code> - this is an internal value within ACA-Py:</p> <pre><code>{\n  \"dif\": {\n    \"issuer_id\": \"did:key:zUC7Dus47jW5Avcne8LLsUvJSdwspmErgehxMWqZZy8eSSNoHZ4x8wgs77sAmQtCADED5RQP1WWhvt7KFNm6GGMxdSGpKu3PX6R9a61G9VoVsiFoRf1yoK6pzhq9jtFP3e2SmU9\",\n    \"presentation_definition\": {\n      \"format\": {\n        \"ldp_vp\": {\n          \"proof_type\": [\n            \"BbsBlsSignature2020\"\n          ]\n        }\n      },\n      \"id\": \"32f54163-7166-48f1-93d8-ff217bdb0654\",\n      \"input_descriptors\": [\n        {\n          \"id\": \"citizenship_input_1\",\n          \"name\": \"Some kind of citizenship check\",\n          \"schema\": [\n            {\n              \"uri\": \"https://www.w3.org/2018/credentials#VerifiableCredential\"\n            },\n            {\n              \"uri\": \"https://w3id.org/citizenship#PermanentResident\"\n            }\n          ],\n          \"constraints\": {\n            \"limit_disclosure\": \"required\",\n            \"fields\": [\n              {\n                \"path\": [\n                  \"$.credentialSubject.familyName\"\n                ],\n                \"purpose\": \"The claim must be from one of the specified issuers\",\n                \"filter\": {\n                  \"const\": \"SMITH\"\n                }\n              }\n            ]\n          }\n        }\n      ]\n    },\n    \"record_ids\": {\n      \"citizenship_input_1\": [ \"1496316f972e40cf9b46b35971182337\" ]\n    }\n  }\n}\n</code></pre>"},{"location":"demo/AliceWantsAJsonCredential/#another-credential-issue-example","title":"Another Credential Issue Example","text":"<p>TBD the following credential is based on the W3C Vaccination schema:</p> <pre><code>{\n  \"connection_id\": \"ad35a4d8-c84b-4a4f-a83f-1afbf134b8b9\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://w3id.org/vaccination/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"VaccinationCertificate\"],\n        \"issuer\": \"did:key:zUC71pj2gpDLfcZ9DE1bMtjZGWCSLhkQsUCaKjqXtCftGkz27894pEX9VvGNiFsaV67gqv2TEPQ2aDaDDdTDNp42LfDdK1LaWSBCfzsQEyaiR1zjZm1RtoRu1ZM6v6vz4TiqDgU\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n            \"id\": \"did:key:aksdkajshdkajhsdkjahsdkjahsdj\",\n            \"type\": \"VaccinationEvent\",\n            \"batchNumber\": \"1183738569\",\n            \"administeringCentre\": \"MoH\",\n            \"healthProfessional\": \"MoH\",\n            \"countryOfVaccination\": \"NZ\",\n            \"recipient\": {\n              \"type\": \"VaccineRecipient\",\n              \"givenName\": \"JOHN\",\n              \"familyName\": \"SMITH\",\n              \"gender\": \"Male\",\n              \"birthDate\": \"1958-07-17\"\n            },\n            \"vaccine\": {\n              \"type\": \"Vaccine\",\n              \"disease\": \"COVID-19\",\n              \"atcCode\": \"J07BX03\",\n              \"medicinalProductName\": \"COVID-19 Vaccine Moderna\",\n              \"marketingAuthorizationHolder\": \"Moderna Biotech\"\n            }\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"demo/AriesOpenAPIDemo/","title":"Aries OpenAPI Demo","text":"<p>What better way to learn about controllers than by actually being one yourself! In this demo, that\u2019s just what happens\u2014you are the controller. You have access to the full set of API endpoints exposed by an ACA-Py instance, and you will see the events coming from ACA-Py as they happen. Using that information, you'll help Alice's and Faber's agents connect, Faber's agent issue an education credential to Alice, and then ask Alice to prove she possesses the credential. Who knows why Faber needs to get the proof, but it lets us show off more protocols.</p>"},{"location":"demo/AriesOpenAPIDemo/#contents","title":"Contents","text":"<ul> <li>Getting Started</li> <li>Running in a Browser</li> <li>Start the Faber Agent</li> <li>Start the Alice Agent</li> <li>Running in Docker</li> <li>Start the Faber Agent</li> <li>Start the Alice Agent</li> <li>Restarting the Docker Containers</li> <li>Using the OpenAPI/Swagger User Interface</li> <li>Establishing a Connection</li> <li>Use the Faber Agent to Create an Invitation</li> <li>Copy the Invitation created by the Faber Agent</li> <li>Use the Alice Agent to Receive Faber's Invitation</li> <li>Tell Alice's Agent to Accept the Invitation</li> <li>The Faber Agent Gets the Request</li> <li>The Faber Agent Completes the Connection</li> <li>Review the Connection Status in Alice's Agent</li> <li>Review the Connection Status in Faber's Agent</li> <li>Basic Messaging Between Agents</li> <li>Sending a message from Alice to Faber</li> <li>Receiving a Basic Message (Faber)</li> <li>Alice's Agent Verifies that Faber has Received the Message</li> <li>Preparing to Issue a Credential</li> <li>Confirming your Schema and Credential Definition</li> <li>Notes</li> <li>Issuing a Credential</li> <li>Faber - Preparing to Issue a Credential</li> <li>Faber - Issuing the Credential</li> <li>Alice Receives Credential</li> <li>Alice Stores Credential in her Wallet</li> <li>Faber Receives Acknowledgment that the Credential was Received</li> <li>Issue Credential Notes</li> <li>Bonus Points</li> <li>Requesting/Presenting a Proof</li> <li>Faber sends a Proof Request</li> <li>Alice - Responding to the Proof Request</li> <li>Faber - Verifying the Proof</li> <li>Present Proof Notes</li> <li>Bonus Points</li> <li>Conclusion</li> </ul>"},{"location":"demo/AriesOpenAPIDemo/#getting-started","title":"Getting Started","text":"<p>We will get started by opening three browser tabs that will be used throughout the lab. Two will be Swagger UIs for the Faber and Alice agent and one for the public ledger (showing the Hyperledger Indy ledger). As well, we'll keep the terminal sessions where we started the demos handy, as we'll be grabbing information from them as well.</p> <p>Let's start with the ledger browser. For this demo, we're going to use an open public ledger operated by the BC Government's VON Team. In your first browser tab, go to: http://test.bcovrin.vonx.io. This will be called the \"ledger tab\" in the instructions below.</p> <p>For the rest of the set up, you can choose to run the terminal sessions in your browser (no local resources needed), or you can run it in Docker on your local system. Your choice, each is covered in the next two sections.</p> <p>Note: In the following, when we start the agents we use several special demo settings. The command we use is this: <code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events --no-auto --bg</code>. In that:</p> <ul> <li>The <code>LEDGER_URL</code> environment variable informs the agent what ledger to use.</li> <li>The <code>--events</code> option indicates that we want the controller to display the webhook events from ACA-Py in the log displayed on the terminal.</li> <li>The <code>--no-auto</code> option indicates that we don't want the ACA-Py agent to automatically handle some events such as connecting. We want the controller (you!) to handle each step of the protocol.</li> <li>The <code>--bg</code> option indicates that the docker container will run in the background, so accidentally hitting Ctrl-C won't stop the process.</li> </ul>"},{"location":"demo/AriesOpenAPIDemo/#running-in-a-browser","title":"Running in a Browser","text":"<p>To run the necessary terminal sessions in your browser, go to the Docker playground service Play with Docker. Don't know about Play with Docker? Check this out to learn more.</p>"},{"location":"demo/AriesOpenAPIDemo/#start-the-faber-agent","title":"Start the Faber Agent","text":"<p>In a browser, go to the Play with Docker home page, Login (if necessary) and click \"Start.\" On the next screen, click (in the left menu) \"+Add a new instance.\"  That will start up a terminal in your browser. Run the following commands to start the Faber agent.</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f faber\n</code></pre> <p>Once the Faber agent has started up (with the invite displayed), click the link near the top of the screen <code>8021</code>. That will start an instance of the OpenAPI/Swagger user interface connected to the Faber instance. Note that the URL on the OpenAPI/Swagger instance is: <code>http://ip....8021.direct...</code>.</p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8021 is the Faber agent.</p> <p>NOTE: Hit \"Ctrl-C\" at any time to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Faber agent by running <code>docker logs -f faber</code></p> Show me a screenshot!"},{"location":"demo/AriesOpenAPIDemo/#start-the-alice-agent","title":"Start the Alice Agent","text":"<p>Now to start Alice's agent. Click the \"+Add a new instance\" button again to open another terminal session. Run the following commands to start Alice's agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f alice\n</code></pre> <p>You can ignore a message like <code>WARNING: your terminal doesn't support cursor position requests (CPR).</code></p> <p>Once the Alice agent has started up (with the <code>invite:</code> prompt displayed), click the link near the top of the screen <code>8031</code>. That will start an instance of the OpenAPI/Swagger User Interface connected to the Alice instance. Note that the URL on the OpenAPI/Swagger instance is: <code>http://ip....8031.direct...</code>.</p> <p>NOTE: Hit \"Ctrl-C\" to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Faber agent by running <code>docker logs -f faber</code></p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8031 is Alice's agent.</p> Show me a screenshot! <p>You are ready to go. Skip down to the Using the OpenAPI/Swagger User Interface section.</p>"},{"location":"demo/AriesOpenAPIDemo/#running-in-docker","title":"Running in Docker","text":"<p>To run the demo on your local system, you must have git, a running Docker installation, and terminal windows running bash. Need more information about getting set up? Click here to learn more.</p>"},{"location":"demo/AriesOpenAPIDemo/#start-the-faber-agent_1","title":"Start the Faber Agent","text":"<p>To begin running the demo in Docker, open up two terminal windows, one each for Faber\u2019s and Alice\u2019s agent.</p> <p>In the first terminal window, clone the ACA-Py repo, change into the demo folder and start the Faber agent:</p> <pre><code>git clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\nLEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f faber\n</code></pre> <p>If all goes well, the agent will show a message indicating it is running. Use the second browser tab to navigate to http://localhost:8021. You should see an OpenAPI/Swagger user interface with a (long-ish) list of API endpoints. These are the endpoints exposed by the Faber agent.</p> <p>NOTE: Hit \"Ctrl-C\" to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Faber agent by running <code>docker logs -f faber</code></p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8021 is the Faber agent.</p> Show me a screenshot!"},{"location":"demo/AriesOpenAPIDemo/#start-the-alice-agent_1","title":"Start the Alice Agent","text":"<p>To start Alice's agent, open up a second terminal window and in it, change to the same <code>demo</code> directory as where Faber's agent was started above. Once there, start Alice's agent:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo alice --events --no-auto --bg\n</code></pre> <p>Once you are back at the command prompt, we'll use docker's logging capability to see what's being written to the terminal:</p> <pre><code>docker logs -f alice\n</code></pre> <p>You can ignore a message like <code>WARNING: your terminal doesn't support cursor position requests (CPR)</code> that may appear.</p> <p>If all goes well, the agent will show a message indicating it is running. Open a third browser tab and navigate to http://localhost:8031. Again, you should see the OpenAPI/Swagger user interface with a list of API endpoints, this time the endpoints for Alice\u2019s agent.</p> <p>NOTE: Hit \"Ctrl-C\" to get back to the command line. When you are done with the command line, you can return to seeing the logs from the Alice agent by running <code>docker logs -f alice</code></p> <p>Remember that the OpenAPI/Swagger browser tab with an address containing 8031 is Alice's agent.</p> Show me a screenshot!"},{"location":"demo/AriesOpenAPIDemo/#restarting-the-docker-containers","title":"Restarting the Docker Containers","text":"<p>When you complete the entire demo (not now!!), you can need to stop the two agents.  To do that, get to the command line by hitting Ctrl-C and running:</p> <pre><code>docker stop faber\ndocker stop alice\n</code></pre>"},{"location":"demo/AriesOpenAPIDemo/#using-the-openapiswagger-user-interface","title":"Using the OpenAPI/Swagger User Interface","text":"<p>Try to organize what you see on your screen to include both the Alice and Faber OpenAPI/Swagger tabs, and both (Alice and Faber) terminal sessions, all at the same time. After you execute an API call in one of the browser tabs, you will see a webhook event from the ACA-Py instance in the terminal window of the other agent. That's a controller's life. See an event, process it, send a response.</p> <p>From time to time you will want to see what's happening on the ledger, so keep that handy as well. As well, if you make an error with one of the commands (e.g. bad data, improperly structured JSON), you will see the errors in the terminals.</p> <p>In the instructions that follow, we\u2019ll let you know if you need to be in the Faber, Alice or Indy browser tab. We\u2019ll leave it to you to track which is which.</p> <p>Using the OpenAPI/Swagger user interface is pretty simple. In the steps below, we\u2019ll indicate what API endpoint you need use, such as <code>POST /connections/create-invitation</code>. That means you must:</p> <ol> <li>scroll to and find that endpoint;</li> <li>click on the endpoint name to expand its section of the UI;</li> <li>click on the <code>Try it out</code> button;</li> <li>fill in any data necessary to run the command;</li> <li>click <code>Execute</code>;</li> <li>check the response to see if the request worked.</li> </ol> <p>So, the mechanical steps are easy. It\u2019s fourth step from the list above that can be tricky. Supplying the right data and, where JSON is involved, getting the syntax correct - braces and quotes can be a pain. When steps don\u2019t work, start your debugging by looking at your JSON.</p> <p>Enough with the preliminaries, let\u2019s get started!</p>"},{"location":"demo/AriesOpenAPIDemo/#establishing-a-connection","title":"Establishing a Connection","text":"<p>We\u2019ll start the demo by establishing a connection between the Alice and Faber agents. We\u2019re starting there to demonstrate that you can use agents without having a ledger. We won\u2019t be using the Indy public ledger at all for this step. Since the agents communicate using DIDComm messaging and connect by exchanging pairwise DIDs and DIDDocs based on (an early version of) the <code>did:peer</code> DID method, a public ledger is not needed.</p>"},{"location":"demo/AriesOpenAPIDemo/#use-the-faber-agent-to-create-an-invitation","title":"Use the Faber Agent to Create an Invitation","text":"<p>In the Faber browser tab, navigate to the <code>POST /connections/create-invitation</code> endpoint. Replace the sample body with and empty production (<code>{}</code>) and execute the call. If successful, you should see a connection id, an invitation, and the invitation URL. The connection ids will be different on each run.</p> <p>Hint: set an Alias on the Invitation, this makes it easier to find the Connection later on</p> Show me a screenshot - Create Invitation Request Show me a screenshot - Create Invitation Response"},{"location":"demo/AriesOpenAPIDemo/#copy-the-invitation-created-by-the-faber-agent","title":"Copy the Invitation created by the Faber Agent","text":"<p>Copy the entire block of the <code>invitation</code> object, from the curly brackets <code>{}</code>, excluding the trailing comma.</p> Show me a screenshot - Create Invitation Response <p>Before switching over to the Alice browser tab, scroll to and execute  the <code>GET /connections</code> endpoint to see the list of Faber's connections. You should see a connection with a <code>connection_id</code> that is identical to the invitation you just created, and that its state is <code>invitation</code>.</p> Show me a screenshot - Faber Connection Status"},{"location":"demo/AriesOpenAPIDemo/#use-the-alice-agent-to-receive-fabers-invitation","title":"Use the Alice Agent to Receive Faber's Invitation","text":"<p>Switch to the Alice browser tab and get ready to execute the <code>POST /connections/receive-invitation</code> endpoint. Select all of the pre-populated text and replace it with the invitation object from the Faber tab. When you click <code>Execute</code> you should get back a connection response with a connection Id, an invitation key, and the state of the connection, which should be <code>invitation</code>.</p> <p>Hint: set an Alias on the Invitation, this makes it easier to find the Connection later on</p> Show me a screenshot - Receive Invitation Request Show me a screenshot - Receive Invitation Response <p>A key observation to make here. The \"copy and paste\" we are doing here from Faber's agent to Alice's agent is what is called an \"out of band\" message. Because we don't yet have a DIDComm connection between the two agents, we have to convey the invitation in plaintext (we can't encrypt it - no channel) using some other mechanism than DIDComm. With mobile agents, that's where QR codes often come in. Once we have the invitation in the receivers agent, we can get back to using DIDComm.</p>"},{"location":"demo/AriesOpenAPIDemo/#tell-alices-agent-to-accept-the-invitation","title":"Tell Alice's Agent to Accept the Invitation","text":"<p>At this point Alice has simply stored the invitation in her wallet. You can see the status using the <code>GET /connections</code> endpoint.</p> Show me a screenshot <p>To complete a connection with Faber, she must accept the invitation and send a corresponding connection request to Faber. Find the <code>connection_id</code> in the connection response from the previous <code>POST /connections/receive-invitation</code> endpoint call. You may note that the same data was sent to the controller as an event from ACA-Py and is visible in the terminal. Scroll to the <code>POST /connections/{conn_id}/accept-invitation</code> endpoint and paste the <code>connection_id</code> in the <code>id</code> parameter field (you will have to click the <code>Try it out</code> button to see the available URL parameters). The response from clicking <code>Execute</code> should show that the connection has a state of <code>request</code>.</p> Show me a screenshot - Accept Invitation Request Show me a screenshot - Accept Invitation Response"},{"location":"demo/AriesOpenAPIDemo/#the-faber-agent-gets-the-request","title":"The Faber Agent Gets the Request","text":"<p>In the Faber terminal session, an event (a web service callback from ACA-Py to the controller) has been received about the request from Alice. Copy the <code>connection_id</code> from the event for the next step.</p> Show me the event <p>Note that the connection ID held by Alice is different from the one held by Faber. That makes sense, as both independently created connection objects, each with a unique, self-generated GUID.</p>"},{"location":"demo/AriesOpenAPIDemo/#the-faber-agent-completes-the-connection","title":"The Faber Agent Completes the Connection","text":"<p>To complete the connection process, Faber will respond to the connection request from Alice. Scroll to the <code>POST /connections/{conn_id}/accept-request</code> endpoint and paste the <code>connection_id</code> you previously copied into the <code>id</code> parameter field (you will have to click the <code>Try it out</code> button to see the available URL parameters). The response from clicking the <code>Execute</code> button should show that the connection has a state of <code>response</code>, which indicates that Faber has accepted Alice's connection request.</p> Show me a screenshot - Accept Connection Request Show me a screenshot - Accept Connection Request"},{"location":"demo/AriesOpenAPIDemo/#review-the-connection-status-in-alices-agent","title":"Review the Connection Status in Alice's Agent","text":"<p>Switch over to the Alice browser tab.</p> <p>Scroll to and execute <code>GET /connections</code> to see a list of Alice's connections, and the information tracked about each connection. You should see the one connection Alice\u2019s agent has, that it is with the Faber agent, and that its state is <code>active</code>.</p> Show me a screenshot - Alice Connection Status <p>As with Faber's side of the connection, Alice received a notification that Faber had accepted her connection request.</p> Show me the event"},{"location":"demo/AriesOpenAPIDemo/#review-the-connection-status-in-fabers-agent","title":"Review the Connection Status in Faber's Agent","text":"<p>You are connected! Switch to the Faber browser tab and run the same <code>GET /connections</code> endpoint to see Faber's view of the connection. Its state is also <code>active</code>. Note the <code>connection_id</code>, you\u2019ll need it later in the tutorial.</p> Show me a screenshot - Faber Connection Status"},{"location":"demo/AriesOpenAPIDemo/#basic-messaging-between-agents","title":"Basic Messaging Between Agents","text":"<p>Once you have a connection between two agents, you have a channel to exchange secure, encrypted messages. In fact these underlying encrypted messages (similar to envelopes in a postal system) enable the delivery of messages that form the higher level protocols, such as issuing Credentials and providing Proofs. So, let's send a couple of messages that contain the simplest of context\u2014text. For this we wil use the Basic Message protocol, Aries RFC 0095.</p>"},{"location":"demo/AriesOpenAPIDemo/#sending-a-message-from-alice-to-faber","title":"Sending a message from Alice to Faber","text":"<p>On Alice's swagger page, scroll to the <code>POST /connections/{conn_id}/send-message</code> endpoint. Click on <code>Try it Out</code> and enter a message in the body provided (for example <code>{\"content\": \"Hello Faber\"}</code>). Enter the connection id of Alice's connection in the field provided. Then click on <code>Execute</code>.</p> Show me a screenshot"},{"location":"demo/AriesOpenAPIDemo/#receiving-a-basic-message-faber","title":"Receiving a Basic Message (Faber)","text":"<p>How does Faber know that a message was sent? If you take a look at Faber's console window, you can see that Faber's agent has raised an Event that the message was received:</p> Show me a screenshot <p>Faber's controller application can take whatever action is necessary to process this message. It could trigger some application code, or it might just be something the Faber application needs to display to its user (for example a reminder about some action the user needs to take).</p>"},{"location":"demo/AriesOpenAPIDemo/#alices-agent-verifies-that-faber-has-received-the-message","title":"Alice's Agent Verifies that Faber has Received the Message","text":"<p>How does Alice get feedback that Faber has received the message? The same way - when Faber's agent acknowledges receipt of the message, Alice's agent raises an Event to let the Alice controller know:</p> Show me a screenshot <p>Again, Alice's agent can take whatever action is necessary, possibly just flagging the message as having been <code>received</code>.</p>"},{"location":"demo/AriesOpenAPIDemo/#preparing-to-issue-a-credential","title":"Preparing to Issue a Credential","text":"<p>The next thing we want to do in the demo is have the Faber agent issue a credential to Alice\u2019s agent. To this point, we have not used the Indy ledger at all. Establishing the connection and messaging has been done with pairwise DIDs based on the <code>did:peer</code> method. Verifiable credentials must be rooted in a public DID ledger to enable the presentation of proofs.</p> <p>Before the Faber agent can issue a credential, it must register a DID on the Indy public ledger, publish a schema, and create a credential definition. In the \u201creal world\u201d, the Faber agent would do this before connecting with any other agents. And, since we are using the handy \"./run_demo faber\" (and \"./run_demo alice\") scripts to start up our agents, the Faber version of the script has already:</p> <ol> <li>registered a public DID and stored it on the ledger;</li> <li>created a schema and registered it on the ledger;</li> <li>created a credential definition and registered it on the ledger.</li> </ol> <p>The schema and credential definition could also be created through this swagger interface.</p> <p>We don't cover the details of those actions in this tutorial, but there are other materials available that go through these details.</p> <p>To Do: Add a link to directions for doing this manually, and to where in the controller Python code this is done.</p>"},{"location":"demo/AriesOpenAPIDemo/#confirming-your-schema-and-credential-definition","title":"Confirming your Schema and Credential Definition","text":"<p>You can confirm the schema and credential definition were published by going back to the Indy ledger browser tab using Faber's public DID. You may have saved that from a previous step, but if not here is an API call you can make to get that information. Using Faber's swagger page and scroll to the <code>GET /wallet/did/public</code> endpoint. Click on <code>Try it Out</code> and <code>Execute</code> and you will see Faber's public DID.</p> Show me a screenshot <p>On the ledger browser of the BCovrin ledger, click the <code>Domain</code> page, refresh, and paste the Faber public DID into the <code>Filter:</code> field:</p> Show me a screenshot <p>The ledger browser should refresh and display the four (4) transactions on the ledger related to this DID:</p> <ul> <li>the initial DID registration</li> <li>registration of the DID endpoint (Faber is an issuer so it has a public endpoint)</li> <li>the registered schema</li> <li>the registered credential definition</li> </ul> Show me the ledger transactions <p>You can also look up the Schema and Credential Definition information using Faber's swagger page. Use the <code>GET /schemas/created</code> endpoint to get a list of schemas, including the one <code>schema_id</code> that the Faber agent has defined. Keep this section of the Swagger page expanded as we'll need to copy the Id as part of starting the issue credential protocol coming next.</p> Show me a screenshot <p>Likewise use the <code>GET /credential-definitions/created</code> endpoint to get the list of the one (in this case) credential definition id created by Faber. Keep this section of the Swagger page expanded as we'll also need to copy the Id as part of starting the issue credential protocol coming next.</p> Show me a screenshot <p>Hint: Remember how the schema and credential definitions were created for you as Faber started up? To do it yourself, use the <code>POST</code> versions of these endpoints. Now you know!</p>"},{"location":"demo/AriesOpenAPIDemo/#notes","title":"Notes","text":"<p>The one time setup work for issuing a credential is complete\u2014creating a DID, schema and credential definition. We can now issue 1 or 1 million credentials without having to do those steps again. Astute readers might note that we did not setup a revocation registry, so we cannot revoke the credentials we issue with that credential definition. You can\u2019t have everything in an \"easy\" tutorial!</p>"},{"location":"demo/AriesOpenAPIDemo/#issuing-a-credential","title":"Issuing a Credential","text":"<p>Triggering the issuance of a credential from the Faber agent to Alice\u2019s agent is done with another API call. In the Faber browser tab, scroll down to the <code>POST /issue-credential-2.0/send</code> and get ready to (but don\u2019t yet) execute the request. Before execution, you need to update most of the data elements in the JSON. We now cover how to update all the fields.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-preparing-to-issue-a-credential","title":"Faber - Preparing to Issue a Credential","text":"<p>First, get the connection Id for Faber's connection with Alice. You can copy that from the Faber terminal (the last received event includes it), or scroll up on the Faber swagger tab to the <code>GET /connections</code> API endpoint, execute, copy it and paste the <code>connection_id</code> value into the same field in the issue credential JSON.</p> Click here to see a screenshot <p>For the following fields, scroll on Faber's Swagger page to the listed endpoint, execute (if necessary), copy the response value and paste as the values of the following JSON items:</p> <ul> <li><code>issuer_did</code> the Faber public DID (use <code>GET /wallet/DID/public</code>), </li> <li><code>schema_id</code> the Id of the schema Faber created (use <code>GET /schemas/created</code>) and,</li> <li><code>cred_def_id</code> the Id of the credential definition Faber created (use <code>GET /credential-definitions/created</code>)</li> </ul> <p>into the <code>filter</code> section's <code>indy</code> subsection. Remove the <code>\"dif\"</code> subsection of the <code>filter</code> section within the JSON, and specify the remaining indy filter criteria as follows:</p> <ul> <li><code>schema_version</code>: set to the last segment of the <code>schema_id</code>, a three part version number that was randomly generated on startup of the Faber agent. Segments of the <code>schema_id</code> are separated by \":\"s.</li> <li><code>schema_issuer_did</code>: set to the same the value as in <code>issuer_did</code>,</li> <li><code>schema_name</code>: set to the second last segment of the <code>schema_id</code>, in this case <code>degree schema</code></li> </ul> <p>Finally, set the remaining values as follows: - <code>auto_remove</code>: set to <code>true</code> (no quotes), see note below - <code>comment</code>: set to any string. It's intended to let Alice know something about the credential being offered. - <code>trace</code>: set to <code>false</code> (no quotes). It's for troubleshooting, performance profiling, and/or diagnostics.</p> <p>By setting <code>auto_remove</code> to true, ACA-Py will automatically remove the credential exchange record after the protocol completes. When implementing a controller, this is the likely setting to use to reduce agent storage usage, but implies if a record of the issuance of the credential is needed, the controller must save it somewhere else. For example, Faber College might extend their Student Information System, where they track all their students, to record when credentials are issued to students, and the Ids of the issued credentials.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-issuing-the-credential","title":"Faber - Issuing the Credential","text":"<p>Finally, we need put into the JSON the data values for the <code>credential_preview</code> section of the JSON. Copy the following and paste it between the square brackets of the <code>attributes</code> item, replacing what is there. Feel free to change the attribute <code>value</code> items, but don't change the labels or names:</p> <pre><code>      {\n        \"name\": \"name\",\n        \"value\": \"Alice Smith\"\n      },\n      {\n        \"name\": \"timestamp\",\n        \"value\": \"1234567890\"\n      },\n      {\n        \"name\": \"date\",\n        \"value\": \"2018-05-28\"\n      },\n      {\n        \"name\": \"degree\",\n        \"value\": \"Maths\"\n      },\n      {\n        \"name\": \"birthdate_dateint\",\n        \"value\": \"19640101\"\n      }\n</code></pre> <p>(Note that the birthdate above is used to present later on to pass an \"age proof\".)</p> <p>OK, finally, you are ready to click <code>Execute</code>. The request should work, but if it doesn\u2019t - check your JSON! Did you get all the quotes and commas right?</p> Show me a screenshot - credential offer <p>To confirm the issuance worked, scroll up on the Faber Swagger page to the <code>issue-credential v2.0</code> section and execute the <code>GET /issue-credential-2.0/records</code> endpoint. You should see a lot of information about the exchange just initiated.</p>"},{"location":"demo/AriesOpenAPIDemo/#alice-receives-credential","title":"Alice Receives Credential","text":"<p>Let\u2019s look at it from Alice\u2019s side. Alice's agent source code automatically handles credential offers by immediately responding with a credential request. Scroll back in the Alice terminal to where the credential issuance started. If you've followed the full script, that is just after where we used the basic message protocol to send text messages between Alice and Faber.</p> <p>Alice's agent first received a notification of a Credential Offer, to which it responded with a Credential Request. Faber received the Credential Request and responded in turn with an Issue Credential message. Scroll down through the events from ACA-Py to the controller to see the notifications of those messages. Make sure you scroll all the way to the bottom of the terminal so you can continue with the process.</p> Show me a screenshot - issue credential"},{"location":"demo/AriesOpenAPIDemo/#alice-stores-credential-in-her-wallet","title":"Alice Stores Credential in her Wallet","text":"<p>We can check (via Alice's Swagger interface) the issue credential status by hitting the <code>GET /issue-credential-2.0/records</code> endpoint. Note that within the results, the <code>cred_ex_record</code> just received has a <code>state</code> of <code>credential-received</code>, but not yet <code>done</code>. Let's address that.</p> Show me a screenshot - check credential exchange status <p>First, we need the <code>cred_ex_id</code> from the API call response above, or from the event in the terminal; use the endpoint <code>POST /issue-credential-2.0/records/{cred_ex_id}/store</code> to tell Alice's ACA-Py instance to store the credential in agent storage (aka the Indy Wallet). Note that in the JSON for that endpoint we can provide a credential Id to store in the wallet by setting a value in the <code>credential_id</code> string. A real controller might use the <code>cred_ex_id</code> for that, or use something else that makes sense in the agent's business scenario (but the agent generates a random credential identifier by default).</p> Show me a screenshot - store credential <p>Now, in Alice\u2019s swagger browser tab, find the <code>credentials</code> section and within that, execute the <code>GET /credentials</code> endpoint. There should be a list of credentials held by Alice, with just a single entry, the credential issued from the Faber agent. Note that the element <code>referent</code> is the value of the <code>credential_id</code> element used in other calls. <code>referent</code> is the name returned in the <code>indy-sdk</code> call to get the set of credentials for the wallet and ACA-Py code does not change it in the response.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-receives-acknowledgment-that-the-credential-was-received","title":"Faber Receives Acknowledgment that the Credential was Received","text":"<p>On the Faber side, we can see by scanning back in the terminal that it receive events to notify that the credential was issued and accepted.</p> Show me Faber's event activity <p>Note that once the credential processing completed, Faber's agent deleted the credential exchange record from its wallet. This can be confirmed by executing the endpoint <code>GET /issue-credential-2.0/records</code></p> Show me a screenshot <p>You\u2019ve done it, issued a credential!  w00t!</p>"},{"location":"demo/AriesOpenAPIDemo/#issue-credential-notes","title":"Issue Credential Notes","text":"<p>Those that know something about the Indy process for issuing a credential and the DIDComm <code>Issue Credential</code> protocol know that there multiple steps to issuing credentials, a back and forth between the issuer and the holder to (at least) offer, request and issue the credential. All of those messages happened, but the two agents took care of those details rather than bothering the controller (you, in this case) with managing the back and forth.</p> <ul> <li>On the Faber agent side, this is because we used the <code>POST /issue-credential-2.0/send</code> administrative message, which handles the back and forth for the issuer automatically. We could have used the other <code>/issue-credential-2.0/</code> endpoints to allow the controller to handle each step of the protocol.</li> <li>On Alice's agent side, this is because the handler for the <code>issue_credential_v2_0</code> event always responds to credential offers with corresponding credential requests.</li> </ul>"},{"location":"demo/AriesOpenAPIDemo/#bonus-points","title":"Bonus Points","text":"<p>If you would like to perform all of the issuance steps manually on the Faber agent side, use a sequence of the other <code>/issue-credential-2.0/</code> messages. Use the <code>GET /issue-credential-2.0/records</code> to both check the credential exchange state as you progress through the protocol and to find some of the data you\u2019ll need in executing the sequence of requests.</p> <p>The following table lists endpoints that you need to call (\"REST service\") and callbacks that your agent will receive (\"callback\") that your need to respond to. See the detailed API docs.</p> Protocol Step Faber (Issuer) Alice (Holder) Notes Send Credential Offer <code>POST /issue-credential-2.0/send-offer</code> REST service Receive Offer /issue_credential_v2_0/ callback Send Credential Request <code>POST /issue-credential-2.0/records/{cred_ex_id}/send-request</code> REST service Receive Request /issue_credential_v2_0/ callback Issue Credential <code>POST /issue-credential-2.0/records/{cred_ex_id}/issue</code> REST service Receive Credential /issue_credential_v2_0/ callback Store Credential <code>POST /issue-credential-2.0/records/{cred_ex_id}/store</code> REST service Receive Acknowledgement /issue_credential_v2_0/ callback Store Credential Id application function"},{"location":"demo/AriesOpenAPIDemo/#requestingpresenting-a-proof","title":"Requesting/Presenting a Proof","text":"<p>Alice now has her Faber credential. Let\u2019s have the Faber agent send a request for a presentation (a proof) using that credential. This should be pretty easy for you at this point.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-sends-a-proof-request","title":"Faber sends a Proof Request","text":"<p>From the Faber browser tab, get ready to execute the <code>POST /present-proof-2.0/send-request</code> endpoint. After hitting <code>Try it Now</code>, erase the data in the block labelled \"Edit Value Model\", replacing it with the text below. Once that is done, replace in the JSON each instance of <code>cred_def_id</code> (there are four instances) and <code>connection_id</code> with the values found using the same techniques we've used earlier in this tutorial. Both can be found by scrolling back a little in the Faber terminal, or you can execute API endpoints we've already covered. You can also change the value of the <code>comment</code> item to whatever you want.</p> <pre><code>{\n  \"comment\": \"This is a comment about the reason for the proof\",\n  \"connection_id\": \"e469e0f3-2b4d-4b12-9ac7-293f23e8a816\",\n  \"presentation_request\": {\n    \"indy\": {\n      \"name\": \"Proof of Education\",\n      \"version\": \"1.0\",\n      \"requested_attributes\": {\n        \"0_name_uuid\": {\n          \"name\": \"name\",\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        },\n        \"0_date_uuid\": {\n          \"name\": \"date\",\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        },\n        \"0_degree_uuid\": {\n          \"name\": \"degree\",\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        },\n        \"0_self_attested_thing_uuid\": {\n          \"name\": \"self_attested_thing\"\n        }\n      },\n      \"requested_predicates\": {\n        \"0_age_GE_uuid\": {\n          \"name\": \"birthdate_dateint\",\n          \"p_type\": \"&lt;=\",\n          \"p_value\": 20030101,\n          \"restrictions\": [\n            {\n              \"cred_def_id\": \"SsX9siFWXJyCAmXnHY514N:3:CL:8:faber.agent.degree_schema\"\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n</code></pre> <p>(Note that the birthdate requested above is used as an \"age proof\", the calculation is something like <code>now() - years(18)</code>, and the presented birthdate must be on or before this date.  You can see the calculation in action in the <code>faber.py</code> demo code.)</p> <p>Notice that the proof request is using a predicate to check if Alice is older than 18 without asking for her age. Not sure what this has to do with her education level! Click <code>Execute</code> and cross your fingers. If the request fails check your JSON!</p> Show me a screenshot - send proof request"},{"location":"demo/AriesOpenAPIDemo/#alice-responding-to-the-proof-request","title":"Alice - Responding to the Proof Request","text":"<p>As before, Alice receives a webhook event from her agent telling her she has received a Proof Request. In our scenario, the ACA-Py instance automatically selects a matching credential and responds with a Proof.</p> Show me Alice's event activity <p>In a real scenario, for example if Alice had a mobile agent on her smartphone, the agent would prompt Alice whether she wanted to respond or not.</p>"},{"location":"demo/AriesOpenAPIDemo/#faber-verifying-the-proof","title":"Faber - Verifying the Proof","text":"<p>Note that in the response, the state is <code>request-sent</code>. That is because when the HTTP response was generated (immediately after sending the request), Alice's agent had not yet responded to the request. We\u2019ll have to do another request to verify the presentation worked. Copy the value of the <code>pres_ex_id</code> field from the event in the Faber terminal and use it in executing the <code>GET /present-proof-2.0/records/{pres_ex_id}</code> endpoint. That should return a result showing the <code>state</code> as <code>done</code> and <code>verified</code> as <code>true</code>. Proof positive!</p> <p>You can see some of Faber's activity below:</p> Show me Faber's event activity"},{"location":"demo/AriesOpenAPIDemo/#present-proof-notes","title":"Present Proof Notes","text":"<p>As with the issue credential process, the agents handled some of the presentation steps without bothering the controller. In this case, Alice's agent processed the presentation request automatically through its handler for the <code>present_proof_v2_0</code> event, and her wallet contained exactly one credential that satisfied the presentation-request from the Faber agent. Similarly, the Faber agent's handler for the event responds automatically and so on receipt of the presentation, it verified the presentation and updated the status accordingly.</p>"},{"location":"demo/AriesOpenAPIDemo/#bonus-points_1","title":"Bonus Points","text":"<p>If you would like to perform all of the proof request/response steps manually, you can call all of the individual <code>/present-proof-2.0</code> messages.</p> <p>The following table lists endpoints that you need to call (\"REST service\") and callbacks that your agent will receive (\"callback\") that you need to respond to. See the detailed API docs.</p> Protocol Step Faber (Verifier) Alice (Holder/Prover) Notes Send Proof Request <code>POST /present-proof-2.0/send-request</code> REST service Receive Proof Request /present_proof_v2_0 callback (webhook) Find Credentials <code>GET /present-proof-2.0/records/{pres_ex_id}/credentials</code> REST service Select Credentials application or user function Send Proof <code>POST /present-proof-2.0/records/{pres_ex_id}/send-presentation</code> REST service Receive Proof /present_proof_v2_0 callback (webhook) Validate Proof <code>POST /present-proof-2.0/records/{pres_ex_id}/verify-presentation</code> REST service Save Proof application data"},{"location":"demo/AriesOpenAPIDemo/#conclusion","title":"Conclusion","text":"<p>That\u2019s the OpenAPI-based tutorial. Feel free to play with the API and learn how it works. More importantly, as you implement a controller, use the OpenAPI user interface to test out the calls you will be using as you go. The list of API calls is grouped by protocol and if you are familiar with the protocols (Aries RFCs) the API call names should be pretty obvious.</p> <p>One limitation of you being the controller is that you don't see the events from the agent that a controller program sees. For example, you, as Alice's agent, are not notified when Faber initiates the sending of a Credential. Some of those things show up in the terminal as messages, but others you just have to know have happened based on a successful API call.</p>"},{"location":"demo/AriesPostmanDemo/","title":"Aries Postman Demo","text":"<p>In these demos we will use Postman as our controller client.</p>"},{"location":"demo/AriesPostmanDemo/#contents","title":"Contents","text":"<ul> <li>Getting Started</li> <li>Installing Postman</li> <li>Creating a workspace</li> <li>Importing the environment</li> <li>Importing the collections</li> <li>Postman basics</li> <li>Experimenting with the vc-api endpoints</li> <li>Register new dids</li> <li>Issue credentials</li> <li>Store and retrieve credentials</li> <li>Verify credentials</li> <li>Prove a presentation</li> <li>Verify a presentation</li> </ul>"},{"location":"demo/AriesPostmanDemo/#getting-started","title":"Getting Started","text":"<p>Welcome to the Postman demo. This is an addition to the available OpenAPI demo, providing a set of collections to test and demonstrate various aca-py functionalities.</p>"},{"location":"demo/AriesPostmanDemo/#installing-postman","title":"Installing Postman","text":"<p>Download, install and launch postman.</p>"},{"location":"demo/AriesPostmanDemo/#creating-a-workspace","title":"Creating a workspace","text":"<p>Create a new postman workspace labeled \"acapy-demo\".</p>"},{"location":"demo/AriesPostmanDemo/#importing-the-environment","title":"Importing the environment","text":"<p>In the environment tab from the left, click the import button. You can paste this link which is the environment file in the ACA-Py repository.</p> <p>Make sure you have the environment set as your active environment.</p>"},{"location":"demo/AriesPostmanDemo/#importing-the-collections","title":"Importing the collections","text":"<p>In the collections tab from the left, click the import button.</p> <p>The following collections are available:</p> <ul> <li>vc-api</li> </ul>"},{"location":"demo/AriesPostmanDemo/#postman-basics","title":"Postman basics","text":"<p>Once you are setup, you will be ready to run postman requests. The order of the request is important, since some values are saved dynamically as environment variables for subsequent calls.</p> <p>You have your environment where you define variables to be accessed by your collections.</p> <p>Each collection consists of a series of requests which can be configured independently.</p>"},{"location":"demo/AriesPostmanDemo/#experimenting-with-the-vc-api-endpoints","title":"Experimenting with the vc-api endpoints","text":"<p>Make sure you have a demo agent available. You can use the following command to deploy one:</p> <pre><code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber --bg\n</code></pre> <p>When running for the first time, please allow some time for the images to build.</p>"},{"location":"demo/AriesPostmanDemo/#register-new-dids","title":"Register new dids","text":"<p>The first 2 requests for this collection will create 2 did:keys. We will use those in subsequent calls to issue <code>Ed25519Signature2020</code> and <code>BbsBlsSignature2020</code> credentials. Run the 2 did creation requests. These requests will use the <code>/wallet/did/create</code> endpoint.</p>"},{"location":"demo/AriesPostmanDemo/#issue-credentials","title":"Issue credentials","text":"<p>For issuing, you must input a w3c compliant json-ld credential and issuance options in your request body. The issuer field must be a registered did from the agent's wallet. The suite will be derived from the did method.</p> <pre><code>{\n    \"credential\":   { \n        \"@context\": [\n            \"https://www.w3.org/2018/credentials/v1\"\n        ],\n        \"type\": [\n            \"VerifiableCredential\"\n        ],\n        \"issuer\": \"did:example:123\",\n        \"issuanceDate\": \"2022-05-01T00:00:00Z\",\n        \"credentialSubject\": {\n            \"id\": \"did:example:123\"\n        }\n    },\n    \"options\": {}\n}\n</code></pre> <p>Some examples have been pre-configured in the collection. Run the requests and inspect the results. Experiment with different credentials.</p>"},{"location":"demo/AriesPostmanDemo/#store-and-retrieve-credentials","title":"Store and retrieve credentials","text":"<p>Your last issued credential will be stored as an environment variable for subsequent calls, such as storing, verifying and including in a presentation.</p> <p>Try running the store credential request, then retrieve the credential with the list and fetch requests. Try going back and forth between the issuance endpoints and the storage endpoints to store multiple different credentials.</p>"},{"location":"demo/AriesPostmanDemo/#verify-credentials","title":"Verify credentials","text":"<p>You can verify your last issued credential with this endpoint or any issued credential you provide to it.</p>"},{"location":"demo/AriesPostmanDemo/#prove-a-presentation","title":"Prove a presentation","text":"<p>Proving a presentation is an action where a holder will prove ownership of a credential by signing or demonstrating authority over the document.</p>"},{"location":"demo/AriesPostmanDemo/#verify-a-presentation","title":"Verify a presentation","text":"<p>The final request is to verify a presentation.</p>"},{"location":"demo/Endorser/","title":"Endorser Demo","text":"<p>There are two ways to run the alice/faber demo with endorser support enabled.</p>"},{"location":"demo/Endorser/#run-faber-as-an-author-with-a-dedicated-endorser-agent","title":"Run Faber as an Author, with a dedicated Endorser agent","text":"<p>This approach runs Faber as an un-privileged agent, and starts a dedicated Endorser Agent in a sub-process (an instance of ACA-Py) to endorse Faber's transactions.</p> <p>Start a VON Network instance and a Tails server:</p> <ul> <li>Following the Building and Starting section of the VON Network Tutorial to get ledger started. You can leave off the <code>--logs</code> option if you want to use the same terminal for running both VON Network and the Tails server. When you are finished with VON Network, follow the Stopping And Removing a VON Network instructions.</li> <li>Run an AnonCreds revocation registry tails server in order to support revocation by following the instructions in the Alice gets a Phone demo.</li> </ul> <p>Start up Faber as Author (note the tails file size override, to allow testing of the revocation registry roll-over):</p> <pre><code>TAILS_FILE_COUNT=5 ./run_demo faber --endorser-role author --revocation\n</code></pre> <p>Start up Alice as normal:</p> <pre><code>./run_demo alice\n</code></pre> <p>You can run all of Faber's functions as normal - if you watch the console you will see that all ledger operations go through the endorser workflow.</p> <p>If you issue more than 5 credentials, you will see Faber creating a new revocation registry (encluding endorser operations).</p>"},{"location":"demo/Endorser/#run-alice-as-an-author-and-faber-as-an-endorser","title":"Run Alice as an Author and Faber as an Endorser","text":"<p>This approach sets up the endorser roles to allow manual testing using the agents' swagger pages:</p> <ul> <li>Faber runs as an Endorser (all of Faber's functions - issue credential, request proof, etc.) run normally, since Faber has ledger write access</li> <li>Alice starts up with a DID aith Author privileges (no ledger write access) and Faber is setup as Alice's Endorser</li> </ul> <p>Start a VON Network and a Tails server using the instructions above.</p> <p>Start up Faber as Endorser:</p> <pre><code>TAILS_FILE_COUNT=5 ./run_demo faber --endorser-role endorser --revocation\n</code></pre> <p>Start up Alice as Author:</p> <pre><code>TAILS_FILE_COUNT=5 ./run_demo alice --endorser-role author --revocation\n</code></pre> <p>Copy the invitation from Faber to Alice to complete the connection.</p> <p>Then in the Alice shell, select option \"D\" and copy Faber's DID (it is the DID displayed on faber agent startup).</p> <p>This starts up the ACA-Py agents with the endorser role set (via the new command-line args) and sets up the connection between the 2 agents with appropriate configuration.</p> <p>Then, in the Alice swagger page you can create a schema and cred def, and all the endorser steps will happen automatically.  You don't need to specify a connection id or explicitly request endorsement (ACA-Py does it all automatically based on the startup args).</p> <p>If you check the endorser transaction records in either Alice or Faber you can see that the endorser protocol executes automatically and the appropriate endorsements were endorsed before writing the transactions to the ledger.</p>"},{"location":"demo/ReusingAConnection/","title":"Reusing a Connection","text":"<p>The Aries RFC 0434 Out of Band protocol enables the concept of reusing a connection such that when using RFC 0023 DID Exchange to establish a connection with an agent with which you already have a connection, you can reuse the existing connection instead of creating a new one. This is something you couldn't do a with the older RFC 0160 Connection Protocol that we used in the early days of Aries. It was a pain, and made for a lousy user experience, as on every visit to an existing contact, the invitee got a new connection.</p> <p>The requirements on your invitations (such as in the example below) are:</p> <ul> <li>The invitation <code>services</code> item MUST be a resolvable DID.</li> <li>Or alternatively, the invitation <code>services</code> item MUST NOT be an <code>inline</code> service.</li> <li>The DID in the invitation <code>services</code> item is the same one in every invitation.</li> </ul> <p>Example invitation:</p> <pre><code>{\n    \"@type\": \"https://didcomm.org/out-of-band/1.1/invitation\",\n    \"@id\": \"77489d63-caff-41fe-a4c1-ec7e2ff00695\",\n    \"label\": \"faber.agent\",\n    \"handshake_protocols\": [\n        \"https://didcomm.org/didexchange/1.0\"\n    ],\n    \"services\": [\n        \"did:sov:4JiUsoK85pVkkB1bAPzFaP\"\n    ]\n}\n</code></pre> <p>Here's the flow that demonstrates where reuse helps. For simplicity, we'll use the terms \"Issuer\" and \"Wallet\" in this example, but it applies to any connection between any two agents (the inviter and the invitee) that establish connections with one another.</p> <ul> <li>The Wallet user is using a browser on the Issuers website and gets to the   point where they are going to be offered a credential. As part of that flow,   they are presented with a QR code that they scan with their wallet app.</li> <li>The QR contains an RFC 0434 Out of Band invitation to connect that the   Wallet processes as the invitee.</li> <li>The Wallet uses the information in the invitation to send an RFC 0023 DID Exchange request   DIDComm message back to the Issuer to initiate establishing a connection.</li> <li>The Issuer responds back to the <code>request</code> with a <code>response</code> message, and the   connection is established.</li> <li>Later, the Wallet user returns to the Issuer's website, and does something   (perhaps starts the process to get another credential) that results in the   same QR code being displayed, and again the users scans the QR code with their   Wallet app.</li> <li>The Wallet recognizes (based on the DID in the <code>services</code> item in the   invitation -- see example below) that it already has a connection to the   Issuer, so instead of sending a DID Exchange <code>request</code> message back to the   Issuer, they send an RFC 0434 Out of Band reuse DIDComm message, and both   parties know to use the existing connection.</li> <li>Had the Wallet used the DID Exchange <code>request</code> message, a new connection     would have been established.</li> </ul> <p>The RFC 0434 Out of Band protocol requirement enables <code>reuse</code> message by the invitee (the Wallet in the flow above) is that the <code>service</code> in the invitation MUST be a resolvable DID that is the same in all of the invitations. In the example invitation above, the DID is a <code>did:sov</code> DID that is resolvable on a public Hyperledger Indy network. The DID could also be a Peer DID of types 2 or 4, which encode the entire DIDDoc contents into the DID identifier (thus they are \"resolvable DIDs\"). What cannot be used is either the old \"unqualified\" DIDs that were commonly used in Aries prior to 2024, and Peer DID type 1. Both of those have DID types include both an identifier and a DIDDoc in the <code>services</code> item of the Out of Band invitation. As noted in the Out of Band specification, <code>reuse</code> cannot be used with such DID types even if the contents are the same.</p> <p>Example invitation:</p> <pre><code>{\n    \"@type\": \"https://didcomm.org/out-of-band/1.1/invitation\",\n    \"@id\": \"77489d63-caff-41fe-a4c1-ec7e2ff00695\",\n    \"label\": \"faber.agent\",\n    \"handshake_protocols\": [\n        \"https://didcomm.org/didexchange/1.0\"\n    ],\n    \"services\": [\n        \"did:sov:4JiUsoK85pVkkB1bAPzFaP\"\n    ]\n}\n</code></pre> <p>The use of conenction reuse can be demonstrated with the Alice / Faber demos as follows. We assume you have already somewhat familiar with your options for running the Alice Faber Demo (e.g. locally or in a browser). Follow those instruction up to the point where you are about to start the Faber and Alice agents.</p> <ol> <li>On a command line, run Faber with these parameters: <code>./run_demo faber    --reuse-connection --events</code>.</li> <li>On a second command line, run Alice as normal, perhaps with the <code>events</code>    option: <code>./run_demo alice --events</code></li> <li>Copy the invitation from the Faber terminal and paste it into the Alice    terminal at the prompt.</li> <li>Verify that the connection was established.</li> <li>If you want, go to the Alice OpenAPI screen (port <code>8031</code>, path       <code>api/docs</code>), and then use the <code>GET Connections</code> to see that Alice has one       connection to Faber.</li> <li>In the Alice terminal, type <code>4</code> to get a prompt for a new connection, and    paste the same invitation as in Step 3 (above).</li> <li>Note from the webhook events in the Faber terminal that the <code>reuse</code> message    is received from Alice, and as a result, no new connection was created.</li> <li>Execute again the <code>GET Connections</code> endpoint on the Alice OpenAPI screen       to confirm that there is still just one established connection.</li> <li>In the Faber terminal, type <code>4</code> to get a new invitation, copy the invitation,    in the Alice terminal, type <code>4</code> to get prompted for an invitation, and paste    in the new invitation from Faber. Again, the <code>reuse</code> webhook event will be    visible in the Faber terminal.</li> <li>Execute again the <code>GET Connections</code> endpoint on the Alice OpenAPI screen       to confirm that there is still just one established connection.</li> <li>Notice that in the invitations in Step 3 and 7 both have the same DID in       the <code>services</code>.</li> <li>Try running the demo again without the <code>--reuse-connection</code> parameter and    compare the <code>services</code> value in the new invitation vs. what was generated in    Steps 3 and 7. It is not a DID, but rather a one time use, inline DIDDoc    item.</li> </ol> <p>While in the demo Faber uses in the invitation the same DID they publish as an issuer (and uses in creating the schema and Cred Def for the demo), Faber could use any resolvable (not inline) DID, including DID Peer types 2 or 4 DIDs, as long as the DID is the same in every invitation. It is the fact that the DID is always the same that tells the invitee that they can reuse an existing connection.</p> <p>Note that the invitation does NOT have to be a multi-use invitation for reuse to be useful, as long as the other requirements (at the top of this document) are met.</p>"},{"location":"deploying/AnonCredsWalletType/","title":"AnonCreds-RS Support","text":"<p>A new wallet type has been added to Aca-Py to support the new anoncreds-rs library:</p> <pre><code>--wallet-type askar-anoncreds\n</code></pre> <p>When Aca-Py is run with this wallet type it will run with an Askar format wallet (and askar libraries) but will use <code>anoncreds-rs</code> instead of <code>credx</code>.</p> <p>There is a new package under <code>aries_cloudagent/anoncreds</code> with code that supports the new library.</p> <p>There are new endpoints (under <code>/anoncreds</code>) for creating a Schema and Credential Definition.  However the new anoncreds code is integrated into the existing Credential and Presentation endpoints (V2.0 endpoints only).</p> <p>Within the protocols, there are new <code>handler</code> libraries to support the new <code>anoncreds</code> format (these are in parallel to the existing <code>indy</code> libraries).</p> <p>The existing <code>indy</code> code are in:</p> <pre><code>aries_cloudagent/protocols/issue_credential/v2_0/formats/indy/handler.py\naries_cloudagent/protocols/indy/anoncreds/pres_exch_handler.py\naries_cloudagent/protocols/present_proof/v2_0/formats/indy/handler.py\n</code></pre> <p>The new <code>anoncreds</code> code is in:</p> <pre><code>aries_cloudagent/protocols/issue_credential/v2_0/formats/anoncreds/handler.py\naries_cloudagent/protocols/present_proof/anoncreds/pres_exch_handler.py\naries_cloudagent/protocols/present_proof/v2_0/formats/anoncreds/handler.py\n</code></pre> <p>The Indy handler checks to see if the wallet type is <code>askar-anoncreds</code> and if so delegates the calls to the anoncreds handler, for example:</p> <pre><code>        # Temporary shim while the new anoncreds library integration is in progress\n        wallet_type = profile.settings.get_value(\"wallet.type\")\n        if wallet_type == \"askar-anoncreds\":\n            self.anoncreds_handler = AnonCredsPresExchangeHandler(profile)\n</code></pre> <p>... and then:</p> <pre><code>        # Temporary shim while the new anoncreds library integration is in progress\n        if self.anoncreds_handler:\n            return self.anoncreds_handler.get_format_identifier(message_type)\n</code></pre> <p>To run the alice/faber demo using the new anoncreds library, start the demo with:</p> <pre><code>--wallet-type askar-anoncreds\n</code></pre> <p>There are no anoncreds-specific integration tests, for the new anoncreds functionality the agents within the integration tests are started with:</p> <pre><code>--wallet-type askar-anoncreds\n</code></pre> <p>Everything should just work!!!</p> <p>Theoretically ATH should work with anoncreds as well, by setting the wallet type (see https://github.com/hyperledger/aries-agent-test-harness#extra-backchannel-specific-parameters).</p>"},{"location":"deploying/AnonCredsWalletType/#revocation-new-in-anoncreds","title":"Revocation (new in anoncreds)","text":"<p>The changes are significant.  Notably:</p> <ul> <li>the old way was that from Indy you got the timestamp of the RevRegEntry used, accumulator and the \"deltas\" -- list of revoked and list of unrevoked credentials for a given range.  I'm not exactly sure what was passed to the AnonCreds library code for building the presentation.</li> <li>In the new way, the AnonCreds library expects the identifier for the revregentry used (aka the timestamp), the accumulator, and the full state (0s and 1s) of the revocation status of all credentials in the registry.</li> <li>The conversion from delta to full state must be handled in the Indy resolver -- not in the \"generic\" ACA-Py code, since the other ledgers automagically provide the full state. In fact, we're likely to update Indy VDR to always provide the full state.  The \"common\" (post resolver) code should get back from the resolver the full state.</li> </ul> <p>The Tails File changes are minimal -- nothing about the file itself changed.  What changed:</p> <ul> <li>the tails-file-server can be published to WITHOUT knowing the ID of the RevRegEntry, since that is not known when the tails file is generated/published.  See: https://github.com/bcgov/indy-tails-server/pull/53 -- basically, by publishing based on the hash.</li> <li>The tails-file is not needed by the issuer after generation. It used to be needed for issuing and revoking credentials. Those are now done without the tails file. See: https://github.com/hyperledger/aries-cloudagent-python/pull/2302/files. That code is already in Main, so you should have it.</li> </ul>"},{"location":"deploying/AnonCredsWalletType/#outstanding-work","title":"Outstanding work","text":"<ul> <li>revocation notifications (not sure if they're included in <code>anoncreds-rs</code> updates, haven't tested them ...)</li> <li>revocation support - complete the revocation implementation (support for unhappy path scenarios)</li> <li> <p>testing - various scenarios like mediation, multitenancy etc.</p> </li> <li> <p>unit tests (in the new anoncreds package) (see https://github.com/hyperledger/aries-cloudagent-python/pull/2596/commits/229ffbba209aff0ea7def5bad6556d93057f3c2a)</p> </li> <li>unit tests (review and possibly update unit tests for the credential and presentation integration)</li> <li>endorsement (not implemented with new anoncreds code)</li> <li>wallet upgrade (askar to askar-anoncreds)</li> <li>update V1.0 versions of the Credential and Presentation endpoints to use anoncreds</li> <li>any other anoncreds issues - https://github.com/hyperledger/aries-cloudagent-python/issues?q=is%3Aopen+is%3Aissue+label%3AAnonCreds</li> </ul>"},{"location":"deploying/AnonCredsWalletType/#retiring-old-indy-and-askar-credx-code","title":"Retiring old Indy and Askar (credx) Code","text":"<p>The main changes for the Credential and Presentation support are in the following two files:</p> <pre><code>aries_cloudagent/protocols/issue_credential/v2_0/messages/cred_format.py\naries_cloudagent/protocols/present_proof/v2_0/messages/pres_format.py\n</code></pre> <p>The <code>INDY</code> handler just need to be re-pointed to the new anoncreds handler, and then all the old Indy code can be retired.</p> <p>The new code is already in place (in comments).  For example for the Credential handler:</p> <pre><code>        To make the switch from indy to anoncreds replace the above with the following\n        INDY = FormatSpec(\n            \"hlindy/\",\n            DeferLoad(\n                \"aries_cloudagent.protocols.present_proof.v2_0\"\n                \".formats.anoncreds.handler.AnonCredsPresExchangeHandler\"\n            ),\n        )\n</code></pre> <p>There is a bunch of duplicated code, i.e. the new anoncreds code was added either as new classes (as above) or as new methods within an existing class.</p> <p>Some new methods were added within the Ledger class.</p> <p>New unit tests were added - in some cases as methods within existing test classes, and in some cases as new classes (whichever was easiest at the time).</p>"},{"location":"deploying/ContainerImagesAndGithubActions/","title":"Container Images and Github Actions","text":"<p>Aries Cloud Agent - Python is most frequently deployed using containers. From the first release of ACA-Py up through 0.7.4, much of the community has built their Aries stack using the container images graciously provided by BC Gov and hosted through their <code>bcgovimages</code> docker hub account. These images have been critical to the adoption of not only ACA-Py but also Hyperledger Aries and SSI more generally.</p> <p>Recognizing how critical these images are to the success of ACA-Py and consistent with Hyperledger's commitment to open collaboration, container images are now built and published directly from the Aries Cloud Agent - Python project repository and made available through the Github Packages Container Registry.</p>"},{"location":"deploying/ContainerImagesAndGithubActions/#image","title":"Image","text":"<p>This project builds and publishes the <code>ghcr.io/hyperledger/aries-cloudagent-python</code> image. Multiple variants are available; see Tags.</p>"},{"location":"deploying/ContainerImagesAndGithubActions/#tags","title":"Tags","text":"<p>ACA-Py is a foundation for building decentralized identity applications; to this end, there are multiple variants of ACA-Py built to suit the needs of a variety of environments and workflows. There are currently two main variants:</p> <ul> <li>\"Standard\" - The default configuration of ACA-Py, including:</li> <li>Aries Askar for secure storage</li> <li>Indy VDR for Indy ledger communication</li> <li>Indy Shared Libraries for AnonCreds</li> <li>\"Indy\" - The legacy configuration of ACA-Py, including:</li> <li>Indy SDK Wallet for secure storage</li> <li>Indy SDK Ledger for Indy ledger communication</li> <li>Indy SDK for AnonCreds</li> </ul> <p>These two image variants are largely distinguished by providers for Indy Network and AnonCreds support. The Standard variant is recommended for new projects. Migration from an Indy based image (whether the new Indy image variant or the original BC Gov images) to the Standard image is outside of the scope of this document.</p> <p>The ACA-Py images built by this project are tagged to indicate which of the above variants it is. Other tags may also be generated for use by developers.</p> <p>Below is a table of all generated images and their tags:</p> Tag Variant Example Description py3.9-X.Y.Z Standard py3.9-0.7.4 Standard image variant built on Python 3.9 for ACA-Py version X.Y.Z py3.10-X.Y.Z Standard py3.10-0.7.4 Standard image variant built on Python 3.10 for ACA-Py version X.Y.Z py3.9-indy-A.B.C-X.Y.Z Indy py3.9-indy-1.16.0-0.7.4 Standard image variant built on Python 3.9 for ACA-Py version X.Y.Z and Indy SDK Version A.B.C py3.10-indy-A.B.C-X.Y.Z Indy py3.10-indy-1.16.0-0.7.4 Standard image variant built on Python 3.10 for ACA-Py version X.Y.Z and Indy SDK Version A.B.C"},{"location":"deploying/ContainerImagesAndGithubActions/#image-comparison","title":"Image Comparison","text":"<p>There are several key differences that should be noted between the two image variants and between the BC Gov ACA-Py images.</p> <ul> <li>Standard Image</li> <li>Based on slim variant of Debian</li> <li>Does NOT include <code>libindy</code></li> <li>Default user is <code>aries</code></li> <li>Uses container's system python environment rather than <code>pyenv</code></li> <li>Askar and Indy Shared libraries are installed as dependencies of ACA-Py through pip from pre-compiled binaries included in the python wrappers</li> <li>Built from repo contents</li> <li>Indy Image</li> <li>Based on slim variant of Debian</li> <li>Built from multi-stage build step (<code>indy-base</code> in the Dockerfile) which includes Indy dependencies; this could be replaced with an explicit <code>indy-python</code> image from the Indy SDK repo</li> <li>Includes <code>libindy</code> but does NOT include the Indy CLI</li> <li>Default user is <code>indy</code></li> <li>Uses container's system python environment rather than <code>pyenv</code></li> <li>Askar and Indy Shared libraries are installed as dependencies of ACA-Py through pip from pre-compiled binaries included in the python wrappers</li> <li>Built from repo contents</li> <li>Includes Indy postgres storage plugin</li> <li><code>bcgovimages/aries-cloudagent</code></li> <li>(Usually) based on Ubuntu</li> <li>Based on <code>von-image</code></li> <li>Default user is <code>indy</code></li> <li>Includes <code>libindy</code> and Indy CLI</li> <li>Uses <code>pyenv</code></li> <li>Askar and Indy Shared libraries built from source</li> <li>Built from ACA-Py python package uploaded to PyPI</li> <li>Includes Indy postgres storage plugin</li> </ul>"},{"location":"deploying/ContainerImagesAndGithubActions/#github-actions","title":"Github Actions","text":"<ul> <li>Tests (<code>.github/workflows/tests.yml</code>) - A reusable workflow that runs tests   for the Standard ACA-Py variant for a given python version.</li> <li>Tests (Indy) (<code>.github/workflows/tests-indy.yml</code>) - A reusable workflow that   runs tests for the Indy ACA-Py variant for a given python and indy version.</li> <li>PR Tests (<code>.github/workflows/pr-tests.yml</code>) - Run on pull requests; runs tests   for the Standard and Indy ACA-Py variants for a \"default\" python version.   Check this workflow for the current default python and Indy versions in use.</li> <li>Nightly Tests (<code>.github/workflows/nightly-tests.yml</code>) - Run nightly; runs   tests for the Standard and Indy ACA-Py variants for all currently supported   python versions. Check this workflow for the set of currently supported   versions and Indy version(s) in use.</li> <li>Publish (<code>.github/workflows/publish.yml</code>) - Run on new release published or   when manually triggered; builds and pushes the Standard ACA-Py variant to the   Github Container Registry.</li> <li>Publish (Indy) (<code>.github/workflows/publish-indy.yml</code>) - Run on new release   published or when manually triggered; builds and pushes the Indy ACA-Py   variant to the Github Container Registry.</li> <li>Integration Tests (<code>.github/workflows/integrationtests.yml</code>) - Run on pull   requests (to the hyperledger fork only); runs BDD integration tests.</li> <li>Black Format (<code>.github/workflows/blackformat.yml</code>) - Run on pull requests;   checks formatting of files modified by the PR.</li> <li>CodeQL (<code>.github/workflows/codeql.yml</code>) - Run on pull requests; performs   CodeQL analysis.</li> <li>Python Publish (<code>.github/workflows/pythonpublish.yml</code>) - Run on release   created; publishes ACA-Py python package to PyPI.</li> <li>PIP Audit (<code>.github/workflows/pipaudit.yml</code>) - Run when manually triggered;   performs pip audit.</li> </ul>"},{"location":"deploying/Databases/","title":"Databases","text":"<p>Your wallet stores secret keys, connections and other information. You have different choices to store this information. The wallet supports 2 different databases to store data, SQLite and PostgreSQL.</p>"},{"location":"deploying/Databases/#sqlite","title":"SQLite","text":"<p>If the wallet is configured the default way in eg. demo-args.yaml, without explicit wallet-storage, a sqlite database file is used.</p> <pre><code># demo-args.yaml\nwallet-type: indy\nwallet-name: wallet\nwallet-key: wallet-password\n</code></pre> <p>For this configuration, a folder called wallet will be created which contains a file called <code>sqlite.db</code>.</p>"},{"location":"deploying/Databases/#postgresql","title":"PostgreSQL","text":"<p>The wallet can be configured to use PostgreSQL as storage.</p> <pre><code># demo-args.yaml\nwallet-type: indy\nwallet-name: wallet\nwallet-key: wallet-password\n\nwallet-storage-type: postgres_storage\nwallet-storage-config: \"{\\\"url\\\":\\\"db:5432\\\",\\\"wallet_scheme\\\":\\\"DatabasePerWallet\\\"}\"\nwallet-storage-creds: \"{\\\"account\\\":\\\"postgres\\\",\\\"password\\\":\\\"mysecretpassword\\\",\\\"admin_account\\\":\\\"postgres\\\",\\\"admin_password\\\":\\\"mysecretpassword\\\"}\"\n</code></pre> <p>In this case the hostname for the database is <code>db</code> on port 5432.</p> <p>A docker-compose file could look like this:</p> <pre><code># docker-compose.yml\nversion: '3'\nservices:\n  # acapy ...\n  # database\n  db:\n    image: postgres:10\n    environment:\n      POSTGRES_PASSWORD: mysecretpassword\n      POSTGRES_USER: postgres\n      POSTGRES_DB: postgres\n    ports:\n      - \"5432:5432\"\n</code></pre>"},{"location":"deploying/IndySDKtoAskarMigration/","title":"Migrating from Indy SDK to Askar","text":"<p>The document summarizes why the Indy SDK is being deprecated, it's replacement (Aries Askar and the \"shared components\"), how to use Aries Askar in a new ACA-Py deployment, and the migration process for an ACA-Py instance that is already deployed using the Indy SDK.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#the-time-has-come-archiving-indy-sdk","title":"The Time Has Come! Archiving Indy SDK","text":"<p>Yes, it\u2019s time. Indy SDK needs to be archived! In this article we\u2019ll explain why this change is needed, why Aries Askar is a faster, better replacement, and how to transition your Indy SDK-based ACA-Py deployment to Askar as soon as possible.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#history-of-indy-sdk","title":"History of Indy SDK","text":"<p>Indy SDK has been the basis of Hyperledger Indy and Hyperledger Aries clients accessing Indy networks for a long time. It has done an excellent job at exactly what you might imagine: being the SDK that enables clients to leverage the capabilities of a Hyperledger Indy ledger.</p> <p>Its continued use has been all the more remarkable given that the last published release of the Indy SDK was in 2020. This speaks to the quality of the implementation \u2014 it just kept getting used, doing what it was supposed to do, and without major bugs, vulnerabilities or demands for new features.</p> <p>However, the architecture of Indy SDK has critical bottlenecks. Most notably, as load increases, Indy SDK performance drops. And with Indy-based ecosystems flourishing and loads exponentially increasing, this means the Aries/Indy community needed to make a change.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#aries-askar-and-the-shared-components","title":"Aries Askar and the Shared Components","text":"<p>The replacement for the Indy SDK is a set of four components, each replacing a part of Indy SDK. (In retrospect, Indy SDK ought to have been split up this way from the start.)</p> <p>The components are:</p> <ol> <li>Aries Askar: the replacement for the \u201cindy-wallet\u201d part of Indy SDK.    Askar is a key management service, handling the creation and use of private    keys managed by Aries agents. It\u2019s also the secure storage for DIDs,    verifiable credentials, and data used by issuers of verifiable credentials    for signing. As the Aries moniker indicates, Askar is suitable for use with    any Aries agent, and for managing any keys, whether for use with Indy or any    other Verifiable Data Registry (VDR).</li> <li>Indy VDR: the interface to publishing to and retrieving data from    Hyperledger Indy networks. Indy VDR is scoped at the appropriate level for    any client application using Hyperledger Indy networks.</li> <li>CredX: a Rust implementation of AnonCreds that evolved from the Indy    SDK implementation. CredX is within the indy-shared-rs repository. It has    significant performance enhancements over the version in the Indy SDK,    particularly for Issuers.</li> <li>Hyperledger AnonCreds: a newer implementation of AnonCreds that is    \u201cledger-agnostic\u201d \u2014 it can be used with Hyperledger Indy and any other    suitable verifiable data registry.</li> </ol> <p>In ACA-Py, we are currently using CredX, but will be moving to Hyperledger AnonCreds soon.</p> <p>If you\u2019re involved in the community, you\u2019ll know we\u2019ve been planning this replacement for almost three years. The first release of the Aries Askar and related components was in 2021. At the end of 2022 there was a concerted effort to eliminate the Indy SDK by creating migration scripts, and removing the Indy SDK from various tools in the community (the Indy CLI, the Indy Test Automation pipeline, and so on). This step is to finish the task.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#performance","title":"Performance","text":"<p>What\u2019s the performance and stability of the replacement? In short, it\u2019s dramatically better. Overall Aries Askar performance is faster, and as the load increases the performance remains constant. Combined with added flexibility and modularization, the community is very positive about the change.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#new-aca-py-deployments","title":"New ACA-Py Deployments","text":"<p>If you are new to ACA-Py, the instructions are easy. Use Aries Askar and the shared components from the start. To do that, simply make sure that you are using the <code>--wallet-type askar</code> configuration parameter. You will automatically be using all of the shared components.</p> <p>As of release 0.9.0, you will get a deprecation warning when you start ACA-Py with the Indy SDK. Switch to Aries Askar to eliminate that warning.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#migrating-existing-indy-sdk-aca-py-deployments-to-askar","title":"Migrating Existing Indy SDK ACA-Py Deployments to Askar","text":"<p>If you have an existing deployment, in changing the <code>--wallet-type</code> configuration setting, your database must be migrated from the Indy SDK format to Aries Askar format. In order to facilitate the migration, an Indy SDK to Askar migration script has been published in the aries-acapy-tools repository. There is lots of information in that repository about the migration tool and how to use it. The following is a summary of the steps you will have to perform. Of course, all deployments are a little (or a lot!) different, and your exact steps will be dependent on where and how you have deployed ACA-Py.</p> <p>Note that in these steps you will have to take your ACA-Py instance offline, so scheduling the maintenance must be a part of your migration plan. You will also want to script the entire process so that downtime and risk of manual mistakes are minimized.</p> <p>We hope that you have one or two test environments (e.g., Dev and Test) to run through these steps before upgrading your production deployment. As well, it is good if you can make a copy of your production database and test the migration on the real (copy) database before the actual upgrade.</p> <ul> <li>Prepare a way to run the Askar Upgrade script from the aries-acapy-tools   repository. For example, you might want to prepare a container that you can   run in the same environment that you run ACA-Py (e.g., within Kubernetes or   OpenShift).</li> <li>Shutdown your ACA-Py instance.</li> <li>Backup the existing wallet using the usual tools you have for backing up the   database.</li> <li>If you are running in a cloud native environment such as Kubernetes, deploy   the Askar Upgrade container, and as needed, update the network policies to   allow the Askar Upgrade container to connect with the wallet database</li> <li>Run the <code>askar-upgrade</code> script. For example:</li> </ul> <pre><code>askar-upgrade \\\n  --strategy dbpw \\\n  --uri postgres://&lt;username&gt;:&lt;password&gt;@&lt;hostname&gt;:&lt;port&gt;/&lt;dbname&gt; \\\n  --wallet-name &lt;wallet name&gt; \\\n  --wallet-key &lt;wallet key&gt;\n</code></pre> <ul> <li>Switch the ACA-Py instance's <code>--wallet-type</code> configuration setting to <code>askar</code></li> <li>Start up the ACA-Py instances.</li> <li>Trouble? Restore the initial database and revert the <code>--wallet-type</code> change     to rollback to the pre-migration state.</li> <li>Check the data.</li> <li>Test the deployment.</li> </ul> <p>It is very important that the Askar Upgrade script has direct access to the database. In our very first upgrade attempt, we ran the Upgrade Askar script from a container running outside of our container orchestration platform (OpenShift) using port forwarding. The script ran EXTREMELY slowly, taking literally hours to run before we finally stopped it. Once we ran the script inside the OpenShift environment, the script ran (for the same database) in about 7 minutes. The entire app downtime was less than 20 minutes.</p>"},{"location":"deploying/IndySDKtoAskarMigration/#questions","title":"Questions?","text":"<p>If you have questions, comments, or suggestions about the upgrade process, please use the Aries Cloud Agent Python channel on Hyperledger Discord, or submit a GitHub issue to the ACA-Py repository.</p>"},{"location":"deploying/Poetry/","title":"Poetry Cheat Sheet for Developers","text":""},{"location":"deploying/Poetry/#introduction-to-poetry","title":"Introduction to Poetry","text":"<p>Poetry is a dependency management and packaging tool for Python that aims to simplify and enhance the development process. It offers features for managing dependencies, virtual environments, and building and publishing Python packages.</p>"},{"location":"deploying/Poetry/#virtual-environments-with-poetry","title":"Virtual Environments with Poetry","text":"<p>Poetry manages virtual environments for your projects to ensure clean and isolated development environments.</p>"},{"location":"deploying/Poetry/#creating-a-virtual-environment","title":"Creating a Virtual Environment","text":"<pre><code>poetry install\n</code></pre>"},{"location":"deploying/Poetry/#activating-the-virtual-environment","title":"Activating the Virtual Environment","text":"<pre><code>poetry shell\n</code></pre> <p>Alternatively you can source the environment settings in the current shell</p> <pre><code>source $(poetry env info --path)/bin/activate\n</code></pre> <p>for powershell users this would be</p> <pre><code>(&amp; ((poetry env info --path) + \"\\Scripts\\activate.ps1\")\n</code></pre>"},{"location":"deploying/Poetry/#deactivating-the-virtual-environment","title":"Deactivating the Virtual Environment","text":"<p>When using <code>poetry shell</code></p> <pre><code>exit\n</code></pre> <p>When using the <code>activate</code> script</p> <pre><code>deactivate\n</code></pre>"},{"location":"deploying/Poetry/#dependency-management","title":"Dependency Management","text":"<p>Poetry uses the <code>pyproject.toml</code> file to manage dependencies. Add new dependencies to this file and update existing ones as needed.</p>"},{"location":"deploying/Poetry/#adding-a-dependency","title":"Adding a Dependency","text":"<pre><code>poetry add package-name\n</code></pre>"},{"location":"deploying/Poetry/#adding-a-development-dependency","title":"Adding a Development Dependency","text":"<pre><code>poetry add --dev package-name\n</code></pre>"},{"location":"deploying/Poetry/#removing-a-dependency","title":"Removing a Dependency","text":"<pre><code>poetry remove package-name\n</code></pre>"},{"location":"deploying/Poetry/#updating-dependencies","title":"Updating Dependencies","text":"<pre><code>poetry update\n</code></pre>"},{"location":"deploying/Poetry/#running-tasks-with-poetry","title":"Running Tasks with Poetry","text":"<p>Poetry provides a way to run scripts and commands without activating the virtual environment explicitly.</p>"},{"location":"deploying/Poetry/#running-a-command","title":"Running a Command","text":"<pre><code>poetry run command-name\n</code></pre>"},{"location":"deploying/Poetry/#running-a-script","title":"Running a Script","text":"<pre><code>poetry run python script.py\n</code></pre>"},{"location":"deploying/Poetry/#building-and-publishing-with-poetry","title":"Building and Publishing with Poetry","text":"<p>Poetry streamlines the process of building and publishing Python packages.</p>"},{"location":"deploying/Poetry/#building-the-package","title":"Building the Package","text":"<pre><code>poetry build\n</code></pre>"},{"location":"deploying/Poetry/#publishing-the-package","title":"Publishing the Package","text":"<pre><code>poetry publish\n</code></pre>"},{"location":"deploying/Poetry/#using-extras","title":"Using Extras","text":"<p>Extras allow you to specify additional dependencies based on project requirements.</p>"},{"location":"deploying/Poetry/#installing-with-extras","title":"Installing with Extras","text":"<pre><code>poetry install -E extras-name\n</code></pre> <p>for example</p> <pre><code>poetry install -E \"askar bbs indy\"\n</code></pre>"},{"location":"deploying/Poetry/#managing-development-dependencies","title":"Managing Development Dependencies","text":"<p>Development dependencies are useful for tasks like testing, linting, and documentation generation.</p>"},{"location":"deploying/Poetry/#installing-development-dependencies","title":"Installing Development Dependencies","text":"<pre><code>poetry install --dev\n</code></pre>"},{"location":"deploying/Poetry/#additional-resources","title":"Additional Resources","text":"<ul> <li>Poetry Documentation</li> <li>PyPI: The Python Package Index</li> </ul>"},{"location":"deploying/RedisPlugins/","title":"ACA-Py Redis Plugins","text":""},{"location":"deploying/RedisPlugins/#aries-acapy-plugin-redis-events-redis_queue","title":"aries-acapy-plugin-redis-events <code>redis_queue</code>","text":"<p>It provides a mechanism to persists both inbound and outbound messages using redis, deliver messages and webhooks, and dispatch events.</p> <p>More details can be found here.</p>"},{"location":"deploying/RedisPlugins/#redis-queue-configuration-yaml","title":"Redis Queue configuration <code>yaml</code>","text":"<pre><code>redis_queue:\n  connection: \n    connection_url: \"redis://default:test1234@172.28.0.103:6379\"\n\n  ### For Inbound ###\n  inbound:\n    acapy_inbound_topic: \"acapy_inbound\"\n    acapy_direct_resp_topic: \"acapy_inbound_direct_resp\"\n\n  ### For Outbound ###\n  outbound:\n    acapy_outbound_topic: \"acapy_outbound\"\n    mediator_mode: false\n\n  ### For Event ###\n  event:\n    event_topic_maps:\n      ^acapy::webhook::(.*)$: acapy-webhook-$wallet_id\n      ^acapy::record::([^:]*)::([^:]*)$: acapy-record-with-state-$wallet_id\n      ^acapy::record::([^:])?: acapy-record-$wallet_id\n      acapy::basicmessage::received: acapy-basicmessage-received\n      acapy::problem_report: acapy-problem_report\n      acapy::ping::received: acapy-ping-received\n      acapy::ping::response_received: acapy-ping-response_received\n      acapy::actionmenu::received: acapy-actionmenu-received\n      acapy::actionmenu::get-active-menu: acapy-actionmenu-get-active-menu\n      acapy::actionmenu::perform-menu-action: acapy-actionmenu-perform-menu-action\n      acapy::keylist::updated: acapy-keylist-updated\n      acapy::revocation-notification::received: acapy-revocation-notification-received\n      acapy::revocation-notification-v2::received: acapy-revocation-notification-v2-received\n      acapy::forward::received: acapy-forward-received\n    event_webhook_topic_maps:\n      acapy::basicmessage::received: basicmessages\n      acapy::problem_report: problem_report\n      acapy::ping::received: ping\n      acapy::ping::response_received: ping\n      acapy::actionmenu::received: actionmenu\n      acapy::actionmenu::get-active-menu: get-active-menu\n      acapy::actionmenu::perform-menu-action: perform-menu-action\n      acapy::keylist::updated: keylist\n    deliver_webhook: true\n</code></pre> <ul> <li><code>redis_queue.connection.connection_url</code>: This is required and is expected in <code>redis://{username}:{password}@{host}:{port}</code> format.</li> <li><code>redis_queue.inbound.acapy_inbound_topic</code>: This is the topic prefix for the inbound message queues. Recipient key of the message are also included in the complete topic name. The final topic will be in the following format <code>acapy_inbound_{recip_key}</code></li> <li><code>redis_queue.inbound.acapy_direct_resp_topic</code>: Queue topic name for direct responses to inbound message.</li> <li><code>redis_queue.outbound.acapy_outbound_topic</code>: Queue topic name for the outbound messages. Used by Deliverer service to deliver the payloads to specified endpoint.</li> <li><code>redis_queue.outbound.mediator_mode</code>: Set to true, if using Redis as a http bridge when setting up a mediator agent. By default, it is set to false.</li> <li><code>event.event_topic_maps</code>: Event topic map</li> <li><code>event.event_webhook_topic_maps</code>: Event to webhook topic map</li> <li><code>event.deliver_webhook</code>: When set to true, this will deliver webhooks to endpoints specified in <code>admin.webhook_urls</code>. By default, set to true.</li> </ul>"},{"location":"deploying/RedisPlugins/#redis-plugin-usage","title":"Redis Plugin Usage","text":""},{"location":"deploying/RedisPlugins/#redis-plugin-with-docker","title":"Redis Plugin With Docker","text":"<p>Running the plugin with docker is simple. An example docker-compose.yml file is available which launches both ACA-Py with redis and an accompanying Redis cluster.</p> <pre><code>docker-compose up --build -d\n</code></pre> <p>More details can be found here.</p>"},{"location":"deploying/RedisPlugins/#without-docker","title":"Without Docker","text":"<p>Installation</p> <pre><code>pip install git+https://github.com/bcgov/aries-acapy-plugin-redis-events.git\n</code></pre> <p>Startup ACA-Py with <code>redis_queue</code> plugin loaded</p> <pre><code>docker network create --subnet=172.28.0.0/24 `network_name`\nexport REDIS_PASSWORD=\" ... As specified in redis_cluster.conf ... \"\nexport NETWORK_NAME=\"`network_name`\"\naca-py start \\\n    --plugin redis_queue.v1_0.events \\\n    --plugin-config plugins-config.yaml \\\n    -it redis_queue.v1_0.inbound redis 0 -ot redis_queue.v1_0.outbound\n    # ... the remainder of your startup arguments\n</code></pre> <p>Regardless of the options above, you will need to startup <code>deliverer</code> and <code>relay</code>/<code>mediator</code> service as a bridge to receive inbound messages. Consider the following to build your <code>docker-compose</code> file which should also start up your redis cluster:</p> <ul> <li> <p>Relay + Deliverer</p> <pre><code>relay:\n    image: redis-relay\n    build:\n        context: ..\n        dockerfile: redis_relay/Dockerfile\n    ports:\n        - 7001:7001\n        - 80:80\n    environment:\n        - REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379\n        - TOPIC_PREFIX=acapy\n        - STATUS_ENDPOINT_HOST=0.0.0.0\n        - STATUS_ENDPOINT_PORT=7001\n        - STATUS_ENDPOINT_API_KEY=test_api_key_1\n        - INBOUND_TRANSPORT_CONFIG=[[\"http\", \"0.0.0.0\", \"80\"]]\n        - TUNNEL_ENDPOINT=http://relay-tunnel:4040\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n    depends_on:\n        - redis-cluster\n        - relay-tunnel\n    networks:\n        - acapy_default\ndeliverer:\n    image: redis-deliverer\n    build:\n        context: ..\n        dockerfile: redis_deliverer/Dockerfile\n    ports:\n        - 7002:7002\n    environment:\n        - REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379\n        - TOPIC_PREFIX=acapy\n        - STATUS_ENDPOINT_HOST=0.0.0.0\n        - STATUS_ENDPOINT_PORT=7002\n        - STATUS_ENDPOINT_API_KEY=test_api_key_2\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n    depends_on:\n        - redis-cluster\n    networks:\n        - acapy_default\n</code></pre> </li> <li> <p>Mediator + Deliverer</p> <pre><code>mediator:\n    image: acapy-redis-queue\n    build:\n        context: ..\n        dockerfile: docker/Dockerfile\n    ports:\n        - 3002:3001\n    depends_on:\n        - deliverer\n    volumes:\n        - ./configs:/home/indy/configs:z\n        - ./acapy-endpoint.sh:/home/indy/acapy-endpoint.sh:z\n    environment:\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n        - TUNNEL_ENDPOINT=http://mediator-tunnel:4040\n    networks:\n        - acapy_default\n    entrypoint: /bin/sh -c '/wait &amp;&amp; ./acapy-endpoint.sh poetry run aca-py \"$$@\"' --\n    command: start --arg-file ./configs/mediator.yml\n\ndeliverer:\n    image: redis-deliverer\n    build:\n        context: ..\n        dockerfile: redis_deliverer/Dockerfile\n    depends_on:\n        - redis-cluster\n    ports:\n        - 7002:7002\n    environment:\n        - REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379\n        - TOPIC_PREFIX=acapy\n        - STATUS_ENDPOINT_HOST=0.0.0.0\n        - STATUS_ENDPOINT_PORT=7002\n        - STATUS_ENDPOINT_API_KEY=test_api_key_2\n        - WAIT_BEFORE_HOSTS=15\n        - WAIT_HOSTS=redis-node-3:6379\n        - WAIT_HOSTS_TIMEOUT=120\n        - WAIT_SLEEP_INTERVAL=1\n        - WAIT_HOST_CONNECT_TIMEOUT=60\n    networks:\n        - acapy_default\n</code></pre> </li> </ul> <p>Both relay and mediator demos are also available.</p>"},{"location":"deploying/RedisPlugins/#aries-acapy-cache-redis-redis_cache","title":"aries-acapy-cache-redis <code>redis_cache</code>","text":"<p>ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose of this plugin is to allow ACA-Py to use Redis as the storage medium for it's caching needs.</p> <p>More details can be found here.</p>"},{"location":"deploying/RedisPlugins/#redis-cache-plugin-configuration-yaml","title":"Redis Cache Plugin configuration <code>yaml</code>","text":"<pre><code>redis_cache:\n  connection: \"redis://default:test1234@172.28.0.103:6379\"\n  max_connection: 50\n  credentials:\n    username: \"default\"\n    password: \"test1234\"\n  ssl:\n    cacerts: ./ca.crt\n</code></pre> <ul> <li><code>redis_cache.connection</code>: This is required and is expected in <code>redis://{username}:{password}@{host}:{port}</code> format.</li> <li><code>redis_cache.max_connection</code>: Maximum number of redis pool connections. Default: 50</li> <li><code>redis_cache.credentials.username</code>: Redis instance username</li> <li><code>redis_cache.credentials.password</code>: Redis instance password</li> <li><code>redis_cache.ssl.cacerts</code></li> </ul>"},{"location":"deploying/RedisPlugins/#redis-cache-usage","title":"Redis Cache Usage","text":""},{"location":"deploying/RedisPlugins/#redis-cache-using-docker","title":"Redis Cache Using Docker","text":"<ul> <li> <p>Running the plugin with docker is simple and straight-forward. There is an example docker-compose.yml file in the root of the project that launches both ACA-Py and an accompanying Redis instance. Running it is as simple as:</p> <pre><code>docker-compose up --build -d\n</code></pre> </li> <li> <p>To launch ACA-Py with an accompanying redis cluster of 6 nodes (3 primaries and 3 replicas), please refer to example docker-compose.cluster.yml and run the following:</p> <p>Note: Cluster requires external docker network with specified subnet</p> <pre><code>docker network create --subnet=172.28.0.0/24 `network_name`\nexport REDIS_PASSWORD=\" ... As specified in redis_cluster.conf ... \"\nexport NETWORK_NAME=\"`network_name`\"\ndocker-compose -f docker-compose.cluster.yml up --build -d\n</code></pre> </li> </ul>"},{"location":"deploying/RedisPlugins/#redis-cache-without-docker","title":"Redis Cache Without Docker","text":"<p>Installation</p> <pre><code>pip install git+https://github.com/Indicio-tech/aries-acapy-cache-redis.git\n</code></pre> <p>Startup ACA-Py with <code>redis_cache</code> plugin loaded</p> <pre><code>aca-py start \\\n    --plugin acapy_cache_redis.v0_1 \\\n    --plugin-config plugins-config.yaml \\\n    # ... the remainder of your startup arguments\n</code></pre> <p>or</p> <pre><code>aca-py start \\\n    --plugin acapy_cache_redis.v0_1 \\\n    --plugin-config-value \"redis_cache.connection=redis://redis-host:6379/0\" \\\n    --plugin-config-value \"redis_cache.max_connections=90\" \\\n    --plugin-config-value \"redis_cache.credentials.username=username\" \\\n    --plugin-config-value \"redis_cache.credentials.password=password\" \\\n    # ... the remainder of your startup arguments\n</code></pre>"},{"location":"deploying/RedisPlugins/#redis-cluster","title":"Redis Cluster","text":"<p>If you startup a redis cluster and an ACA-Py agent loaded with either <code>redis_queue</code> or <code>redis_cache</code> plugin or both, then during the initialization of the plugin, it will bind an instance of <code>redis.asyncio.RedisCluster</code> (onto the <code>root_profile</code>). Other plugin will have access to this redis client for it's functioning. This is done for efficiency and to avoid duplication of resources.</p>"},{"location":"deploying/UpgradingACA-Py/","title":"Upgrading ACA-Py Data","text":"<p>Some releases of ACA-Py may be improved by, or even require, an upgrade when moving to a new version. Such changes are documented in the CHANGELOG.md, and those with ACA-Py deployments should take note of those upgrades. This document summarizes the upgrade system in ACA-Py.</p>"},{"location":"deploying/UpgradingACA-Py/#version-information-and-automatic-upgrades","title":"Version Information and Automatic Upgrades","text":"<p>The file version.py contains the current version of a running instance of ACA-Py. In addition, a record is made in the ACA-Py secure storage (database) about the \"most recently upgraded\" version. When deploying a new version of ACA-Py, the version.py value will be higher than the version in secure storage. When that happens, an upgrade is executed, and on successful completion, the version is updated in secure storage to match what is in version.py.</p> <p>Upgrades are defined in the Upgrade Definition YML file. For a given version listed in the follow, the corresponding entry is what actions are required when upgrading from a previous version. If a version is not listed in the file, there is no upgrade defined for that version from its immediate predecessor version.</p> <p>Once an upgrade is identified as needed, the process is:</p> <ul> <li>Collect (if any) the actions to be taken to get from the version recorded in secure storage to the current version.py</li> <li>Execute the actions from oldest to newest.</li> <li>If the same action is collected more than once (e.g., \"Resave the Connection Records\" is defined for two different versions), perform the action only once.</li> <li>Store the current ACA-Py version (from version.py) in the secure storage   database.</li> </ul>"},{"location":"deploying/UpgradingACA-Py/#forced-offline-upgrades","title":"Forced Offline Upgrades","text":"<p>In some cases, it may be necessary to do an offline upgrade, where ACA-Py is taken off line temporarily, the database upgraded explicitly, and then ACA-Py re-deployed as normal. As yet, we do not have any use cases for this, but those deploying ACA-Py should be aware of this possibility. For example, we may at some point need an upgrade that MUST NOT be executed by more than one ACA-Py instance. In that case, a \"normal\" upgrade could be dangerous for deployments on container orchestration platforms like Kubernetes.</p> <p>If the Maintainers of ACA-Py recognize a case where ACA-Py must be upgraded while offline, a new Upgrade feature will be added that will prevent the \"auto upgrade\" process from executing. See Issue 2201 and Pull Request 2204 for the status of that feature.</p> <p>Those deploying ACA-Py upgrades for production installations (forced offline or not) should check in each CHANGELOG.md release entry about what upgrades (if any) will be run when upgrading to that version, and consider how they want those upgrades to run in their ACA-Py installation. In most cases, simply deploying the new version should be OK. If the number of records to be upgraded is high (such as a \"resave connections\" upgrade to a deployment with many, many connections), you may want to do a test upgrade offline first, to see if there is likely to be a service disruption during the upgrade. Plan accordingly!</p>"},{"location":"deploying/UpgradingACA-Py/#tagged-upgrades","title":"Tagged upgrades","text":"<p>Upgrades are defined in the Upgrade Definition YML file, in addition to specifying upgrade actions by version they can also be specified by named tags. Unlike version based upgrades where all applicable version based actions will be performed based upon sorted order of versions, with named tags only actions corresponding to provided tags will be performed. Note: <code>--force-upgrade</code> is required when running name tags based upgrade (i.e. providing <code>--named-tag</code>).</p> <p>Tags are specified in YML file as below:</p> <pre><code>fix_issue_rev_reg:\n  fix_issue_rev_reg_records: true\n</code></pre> <p>Example:</p> <pre><code> ./scripts/run_docker upgrade --force-upgrade --named-tag fix_issue_rev_reg\n\n# In case, running multiple tags [say test1 &amp; test2]:\n ./scripts/run_docker upgrade --force-upgrade --named-tag test1 --named-tag test2\n</code></pre>"},{"location":"deploying/UpgradingACA-Py/#subwallet-upgrades","title":"Subwallet upgrades","text":"<p>With multitenant enabled, there is a subwallet associated with each tenant profile, so there is a need to upgrade those sub wallets in addition to the base wallet associated with root profile.</p> <p>There are 2 options to perform such upgrades:</p> <ul> <li><code>--upgrade-all-subwallets</code></li> </ul> <p>This will apply the upgrade steps to all sub wallets (tenant profiles) and the base wallet (root profiles).</p> <ul> <li><code>--upgrade-subwallet</code></li> </ul> <p>This will apply the upgrade steps to specified sub wallets (identified by wallet id) and the base wallet.</p> <p>Note: multiple specifications allowed</p>"},{"location":"deploying/UpgradingACA-Py/#exceptions","title":"Exceptions","text":"<p>There are a couple of upgrade exception conditions to consider, as outlined in the following sections.</p>"},{"location":"deploying/UpgradingACA-Py/#no-version-in-secure-storage","title":"No version in secure storage","text":"<p>Versions prior to ACA-Py 0.8.1 did not automatically populate the secure storage \"version\" record. That only occurred if an upgrade was explicitly executed. As of ACA-Py 0.8.1, the version record is added immediately after the secure storage database is created. If you are upgrading to ACA-Py 0.8.1 or later, and there is no version record in the secure storage, ACA-Py will assume you are running version 0.7.5, and execute the upgrades from version 0.7.5 to the current version. The choice of 0.7.5 as the default is safe because the same upgrades will be run on any version of ACA-Py up to and including 0.7.5, as can be seen in the Upgrade Definition YML file. Thus, even if you are really upgrading from (for example) 0.6.2, the same upgrades are needed as from 0.7.5 to a post-0.8.1 version.</p>"},{"location":"deploying/UpgradingACA-Py/#forcing-an-upgrade","title":"Forcing an upgrade","text":"<p>If you need to force an upgrade from a given version of ACA-Py, a pair of configuration options can be used together. If you specify \"<code>--from-version &lt;ver&gt;</code>\" and \"<code>--force-upgrade</code>\", the <code>--from-version</code> version will override what is found (or not) in secure storage, and the upgrade will be from that version to the current one. For example, if you have \"0.8.1\" in your \"secure storage\" version, and you know that the upgrade for version 0.8.1 has not been executed, you can use the parameters <code>--from-version v0.7.5 --force-upgrade</code> to force the upgrade on next starting an ACA-Py instance. However, given the few upgrades defined prior to version 0.8.1, and the \"no version in secure storage\" handling, it is unlikely this capability will ever be needed. We expect to deprecate and remove these options in future (post-0.8.1) ACA-Py versions.</p>"},{"location":"deploying/deploymentModel/","title":"Deployment Model","text":""},{"location":"deploying/deploymentModel/#aries-cloud-agent-python-aca-py-deployment-model","title":"Aries Cloud Agent-Python (ACA-Py) - Deployment Model","text":"<p>This document is a \"concept of operations\" for an instance of an Aries cloud agent deployed from the primary artifact (a PyPi package) produced by this repo. In such a deployment there are always two components - a configured agent itself, and a controller that injects into that agent the business rules for the particular agent instance (see diagram).</p> <p></p> <p>The deployed agent messages with other agents via DIDComm protocols, and as events associated with those messages occur, sends webhook HTTP notifications to the controller. The agent also exposes for the controller's exclusive use an HTTP API covering all of the administrative handlers for those events. The controller receives the notifications from the agent, decides (with business rules - possible by asking a person using a UI) how to respond to the event and calls back to the agent via the HTTP API. Of course, the controller may also initiate events (e.g. messaging another agent) by calling that same API.</p> <p>The following is an example of the interactions involved in creating a connection using the DIDComm \"Establish Connection\" protocol. The controller requests from the agent (via the administrative API) a connection invitation from the agent, and receives one back. The controller provides it to another agent (perhaps by displaying it in a QR code). Shortly after, the agent receives a DIDComm \"Connection Request\" message. The agent, sends it to the controller. The controller decides to accept the connection and calls the API with instructions to the agent to send a \"Connection Response\" message to the other agent. Since the controller always wants to know with whom a connection has been created, the controller also sends instructions to the agent (via the API, of course) to send a request presentation message to the new connection. And so on... During the interactions, the agent is tracking the state of the connections, and the state of the protocol instances (threads). Likewise, the controller may also be retaining state - after all, it's an application that could do anything.</p> <p>Most developers will configure a \"black box\" instance of the ACA-Py. They need to know how it works, the DIDComm protocols it supports, the events it will generate and the administrative API it exposes. However, they don't need to drill into and maintain the ACA-Py code. Such developers will build controller applications (basically, traditional web apps) that at their simplest, use an HTTP interface to receive notification and send HTTP requests to the agent. It's the business logic implemented in, or accessed by the controller that gives the deployment its personality and role.</p> <p>Note: the ACA-Py agent is designed to be stateless, persisting connection and protocol state to storage (such as Postgres database). As such, agents can be deployed to support horizontal scaling as necessary. Controllers can also be implemented to support horizontal scaling.</p> <p>The sections below detail the internals of the ACA-Py and it's configurable elements, and the conceptual elements of a controller. There is no \"Aries controller\" repo to fork, as it is essentially just a web app. There are demos of using the elements in this repo, and several sample applications that you can use to get started on your on controller.</p>"},{"location":"deploying/deploymentModel/#aries-cloud-agent","title":"Aries Cloud Agent","text":"<p>Aries cloud agent implement services to manage the execution of DIDComm messaging protocols for interacting with other DIDComm agents, and exposes an administrative HTTP API that supports a controller to direct how the agent should respond to messaging events. The agent relies on the controller to provide the business rules for handling the messaging events, and to initiate the execution of new DIDComm protocol instances. The internals of an ACA-Py instance is diagramed below.</p> <p></p> <p>Instances of the Aries cloud agents are configured with the following sub-components:</p> <ul> <li>Transport Plugins - pluggable transport-specific message sender/receiver modules that interact with other agents. Messages outside the plugins are transport-agnostic JSON structures. Current modules include HTTP and WebSockets. In the future, we might add ZMQ, SMTP and so on.</li> <li>Conductor receives inbound messages from, and sends outbound messages to, the transport plugins. After internal processing, the conductor passes inbound messages to, and receives outbound messages from, the Dispatcher. In processing the messages, the conductor manages the message\u2019s protocol instance thread state, retrieving the state on inbound messages and saving the state on outbound messages. The conductor handles generic decorators in messages such as verifying and generating signatures on message data elements, internationalization and so on.</li> <li>Dispatcher handles the distribution of messages to the DIDComm protocol message handlers and the responses received. The dispatcher passes to the conductor the thread state to be persistance and message data (if any) to be sent out from the Aries cloud agent instance.</li> <li>DIDComm Protocols - implement the DIDComm protocols supported by the agent instance, including the state object for the protocol, the DIDComm message handlers and the admin message handlers. Protocols are bundled as Python modules and loaded for during the agent deployment. Each protocol contributes the admin messages for the protocol to the controller REST interface. The protocols implement a number of events that invoke the controller via webhooks so that controller\u2019s business logic can respond to the event.</li> <li>Controller REST API - a dynamically generated REST API (with a Swagger/OpenAPI user interface) based on the set of DIDComm protocols included in the agent deployment. The controller, activated via the webhooks from the protocol DIDComm message handlers, controls the Aries cloud agent by calling the REST API that invoke the protocol admin message handlers.</li> <li>Handler API - provides abstract interfaces to various handlers needed by the protocols and core Aries cloud agent components for accessing the secure storage (wallet), other storage, the ledger and so on. The API calls the handler implementations configured into the agent deployment.</li> <li>Handler Plugins - are the handler implementations called from the Handler API. The plugins may be internal to the Agent (in the same process space) or could be external (for example, in other processes/containers).</li> <li>Secure Storage Plugin - the Indy SDK is embedded in the Aries cloud agent and implements the default secure storage. An Aries cloud agent can be configured to use one of a number of indy-sdk storage implementations - in-memory, SQLite and Postgres at this time.</li> <li>Ledger Interface Plugin - In the current Aries cloud agent implementation, the Indy SDK provides an interface to an Indy-based public ledger for verifiable credential protocols. In future, ledger implementations (including those other than Indy) might be moved into the DIDComm protocol modules to be included as needed within a configured Aries cloud agent instance based on the DIDComm protocols used by the agent.</li> </ul>"},{"location":"deploying/deploymentModel/#controller","title":"Controller","text":"<p>A controller provides the personality of Aries cloud agent instance - the business logic (human, machine or rules driven) that drive the behaviour of the agent. The controller\u2019s \u201cBusiness Logic\u201d in a cloud agent could be built into the controller app, could be an integration back to an enterprise system, or even a user interface for an individual. In all cases, the business logic provide responses to agent events or initiates agent actions. A deployed controller talks to a single Aries cloud agent deployment and manages the configuration of that agent. Both can be configured and deployed to support horizontal scaling.</p> <p></p> <p>Generically, a controller is a web app invoked by HTTP webhook calls from its corresponding Aries cloud agent and invoking the DIDComm administration capabilities of the Aries cloud agent by calling the REST API exposed by that cloud agent. As well as responding to Aries cloud agent events, the controller initiates DIDComm protocol instances using the same REST API.</p> <p>The controller and Aries cloud agent deployment MUST secure the HTTP interface between the two components. The interface provides the same HTTP integration between services as modern apps found in any enterprise today, and must be correspondingly secured.</p> <p>A controller implements the following capabilities.</p> <ul> <li>Initiator - provides a mechanism to initiate new DIDComm protocol instances. The initiator invokes the REST API exposed by the Aries cloud agent to initiate the creation of a DIDComm protocol instance. For example, a permit-issuing service uses this mechanism to issue a Verifiable Credential associated with the issuance of a new permit.</li> <li>Responder - subscribes to and responds to events from the Aries cloud agent protocol message handlers, providing business-driven responses. The responder might respond immediately, or the event might cause a delay while the decision is determined, perhaps by sending the request to a person to decide. The controller may persist the event response state if the event is asynchronous - for example, when the event is passed to a person who may respond when they next use the web app.</li> <li>Configuration - manages the controller configuration data and the configuration of the Aries cloud agent.  Configuration in this context includes things like:</li> <li>Credentials and Proof Requests to be Issued/Verified (respectively) by the Aries cloud agent.</li> <li>The configuration of the webhook handler to which the responder subscribes.</li> </ul> <p>While there are several examples of controllers, there is no \u201ccookie cutter\u201d repository to fork and customize. A controller is just a web service that receives HTTP requests (webhooks) and sends HTTP messages to the Aries cloud agent it controls via the REST API exposed by that agent.</p>"},{"location":"deploying/deploymentModel/#deployment","title":"Deployment","text":"<p>The Aries cloud agent CI pipeline configured into the repository generates a PyPi package as an artifact. Implementers will generally have a controller repository, possibly copied from an existing controller instance, that has the code (business logic) for the controller and the configuration (transports, handlers, DIDComm protocols, etc.) for the Aries cloud agent instance. In the most common scenario, the Aries cloud agent and controller instances will be deployed based on the artifacts (e.g. container images) generated from that controller repository. With the simple HTTP-based interface between the controller and Aries cloud agent, both components can be horizontally scaled as needed, with a load balancer between the components. The configuration of the Aries cloud agent to use the Postgres wallet supports enterprise scale agent deployments.</p> <p>Current examples of deployed instances of Aries cloud agent and controllers include:</p> <ul> <li>indy-email-verification - a web app Controller that sends an email to a given email address with an embedded DIDComm invitation and on establishment of a connection, offers and provides the connected agent with an email control verifiable credential.</li> <li>iiwbook - a web app Controller that on creation of a DIDComm connection, requests a proof of email control, and then sends to the connection a verifiable credential proving attendance at IIW. In between the proof and issuance is a human approval step using a simple web-based UI that implements a request queue.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/","title":"Supporting AnonCreds in W3C VC/VP Formats in Aries Cloud Agent Python","text":"<p>This design proposes to extend the Aries Cloud Agent Python (ACA-PY) to support Hyperledger AnonCreds credentials and presentations in the W3C Verifiable Credentials (VC) and Verifiable Presentations (VP) Format. The aim is to transition from the legacy AnonCreds format specified in Aries-Legacy-Method to the W3C VC format.</p>"},{"location":"design/AnoncredsW3CCompatibility/#overview","title":"Overview","text":"<p>The pre-requisites for the work are:</p> <ul> <li>The availability of the AnonCreds RS library supporting the generation and processing of AnonCreds VCs in W3C VC format.</li> <li>The availability of the AnonCreds RS library supporting the generation and verification of AnonCreds VPs in W3C VP format.</li> <li>The availability of support in the AnonCreds RS Python Wrapper for the W3C VC/VP capabilities in AnonCreds RS.</li> <li>Agreement on the Aries Issue Credential v2.0 and Present Proof v2.0 protocol attachment formats to use when issuing AnonCreds W3C VC format credentials, and when presenting AnonCreds W3C VP format presentations.</li> <li>For issuing, use the (proposed) RFC 0809 VC-DI Attachments</li> <li>For presenting, use the RFC 0510 DIF Presentation Exchange Attachments</li> </ul> <p>As of 2024-01-15, these pre-requisites have been met.</p>"},{"location":"design/AnoncredsW3CCompatibility/#impacts-on-aca-py","title":"Impacts on ACA-Py","text":""},{"location":"design/AnoncredsW3CCompatibility/#issuer","title":"Issuer","text":"<p>Issuer support needs to be added for using the RFC 0809 VC-DI attachment format when sending Issue Credential v2.0 protocol<code>offer</code> and <code>issue</code> messages and when receiving <code>request</code> messages.</p> <p>Related notes:</p> <ul> <li>The Issue Credential v1.0 protocol will not be updated to support AnonCreds W3C VC format credentials.</li> <li>Once an instance of the Issue Credential v2.0 protocol is started using RFC 0809 VC-DI format attachments, subsequent messages in the protocol MUST use RFC 0809 VC-DI attachments.</li> <li>The ACA-Py maintainers are discussing the possibility of making pluggable the Issue Credential v2.0 and Present Proof v2.0 attachment formats, to simplify supporting additional formats, including RFC 0809 VC-DI.</li> </ul> <p>A mechanism must be defined such that an Issuer controller can use the ACA-Py Admin API to initiate the sending of an AnonCreds credential Offer using the RFC 0809 VC-DI attachment format.</p> <p>A credential's encoded attributes are not included in the issued AnonCreds W3C VC format credential. To be determined how that impacts the issuing process.</p>"},{"location":"design/AnoncredsW3CCompatibility/#verifier","title":"Verifier","text":"<p>A verifier wanting a W3C VP Format presentation will send the Present Proof v2.0 <code>request</code> message with an RFC 0510 DIF Presentation Exchange format attachment.</p> <p>If needed, the RFC 0510 DIF Presentation Exchange document will be clarified and possibly updated to enable its use for handling AnonCreds W3C VP format presentations.</p> <p>An AnonCreds W3C VP format presentation does not include the encoded revealed attributes, and the encoded values must be calculated as needed. To be determined where those would be needed.</p>"},{"location":"design/AnoncredsW3CCompatibility/#holder","title":"Holder","text":"<p>A holder must support RFC 0809 VC-DI attachments when receiving Issue Credential v2.0 <code>offer</code> and <code>issue</code> messages, and when sending <code>request</code> messages.</p> <p>On receiving an Issue Credential v2.0 <code>offer</code> message with a RFC 0809 VC-DI, the holder MUST respond using the RFC 0809 VC-DI on the subsequent <code>request</code> message.</p> <p>On receiving a credential from an issuer in an RFC 0809 VC-DI attachment, the holder must process and store the credential for subsequent use in presentations.</p> <ul> <li>The AnonCreds verifiable credential MUST support being used in both legacy AnonCreds and W3C VP format (DIF Presentation Exchange) presentations.</li> </ul> <p>On receiving an RFC 0510 DIF Presentation Exchange <code>request</code> message, a holder must include AnonCreds verifiable credentials in the search for credentials satisfying the request, and if found and selected for use, must construct the presentation using the RFC 0510 DIF Presentation Exchange presentation format, with an embedded AnonCreds W3C VP format presentation.</p>"},{"location":"design/AnoncredsW3CCompatibility/#issues-to-consider","title":"Issues to consider","text":"<ul> <li>If and how the W3C VC Format attachments for the Issue Credential V2.0 and Present Proof V2 Aries DIDComm Protocols should be used when using AnonCreds W3C VC Format credentials. Anticipated triggers:</li> <li>An Issuer Controller invokes the Admin API to trigger an Issue Credential v2.0 protocol instance such that the RFC 0809 VC-DI will be used.</li> <li>A Holder receives an Issue Credential v2.0 <code>offer</code> message with an RFC 0809 VC-DI attachment.</li> <li>A Verifier initiates a Present Proof v2.0 protocol instance with an RFC 0510 DIF Presentation Exchange that can be satisfied by AnonCreds VCs held by the holder.</li> <li>A Holder receives a present proof <code>request</code> message with an RFC 0510 DIF Presentation Exchange format attachment that can be satisfied with AnonCreds credentials held by the holder.<ul> <li>How are the <code>restrictions</code> and <code>revocation</code> data elements conveyed?</li> </ul> </li> <li>How AnonCreds W3C VC Format verifiable credentials are stored by the holder such that they will be discoverable when needed for creating verifiable presentations.</li> <li>How and when multiple signatures can/should be added to a W3C VC Format credential, enabling both AnonCreds and non-AnonCreds signatures on a single credential and their use in presentations. Completing a multi-signature controller is out of scope, however we want to consider and ensure the design is fundamentally compatible with multi-sig credentials.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#flow-chart","title":"Flow Chart","text":""},{"location":"design/AnoncredsW3CCompatibility/#key-questions","title":"Key Questions","text":""},{"location":"design/AnoncredsW3CCompatibility/#what-is-the-roadmap-for-delivery-what-will-we-build-first-then-second","title":"What is the roadmap for delivery? What will we build first, then second?","text":"<p>It appears that the issue and presentation sides can be approached independently, assuming that any stored AnonCreds VC can be used in an AnonCreds W3C VP format presentation.</p>"},{"location":"design/AnoncredsW3CCompatibility/#issue-credential","title":"Issue Credential","text":"<ol> <li>Update Admin API endpoints to initiate an Issue Credential v2.0 protocol to issue an AnonCreds credential in W3C VC format using RFC 0809 VC-DI format attachments.</li> <li>Add support for the RFC 0809 VC-DI message attachment formats.</li> <li>Should the attachment format be made pluggable as part of this? From the maintainers: If we did make it pluggable, this would be the point where that would take place. Since these values are hard coded, it is not pluggable currently, as noted. I've been dissatisfied with how this particular piece works for a while. I think making it pluggable, if done right, could help clean it up nicely. A plugin would then define their own implementation of V20CredFormatHandler. (@dbluhm)</li> <li>Update the v2.0 Issue Credential protocol handler to support a \"RFC 0809 VC-DI mode\" such that when a protocol instance starts with that format, it continues with it until completion, supporting issuing AnonCreds credentials in the process. This includes both the sending and receiving of all protocol message types.</li> </ol>"},{"location":"design/AnoncredsW3CCompatibility/#present-proof","title":"Present Proof","text":"<ol> <li>Adjust as needed the sending of a Present Proof request using the RFC 0510 DIF Presentation Exchange with support (to be defined) for requesting AnonCreds VCs.</li> <li>Adjust as needed the processing of a Present Proof <code>request</code> message with an RFC 0510 DIF Presentation Exchange attachment so that AnonCreds VCs can found and used in the subsequent response.</li> <li>AnonCreds VCs issued as legacy or W3C VC format credentials should be usable in AnonCreds W3C VP format presentations.</li> <li>Update the creation of an RFC 0510 DIF Presentation Exchange presentation submission to support the use of AnonCreds VCs as the source of the VPs.</li> <li>Update the verifier receipt of a Present Proof v2.0 <code>presentation</code> message with an RFC 0510 DIF Presentation Exchange containing AnonCreds W3C VP(s) derived from AnonCreds source VCs.</li> </ol>"},{"location":"design/AnoncredsW3CCompatibility/#what-are-the-functions-we-are-going-to-wrap","title":"What are the functions we are going to wrap?","text":"<p>After thoroughly reviewing upcoming changes from anoncreds-rs PR273, the classes or <code>AnoncredsObject</code> impacted by changes are as follows:</p> <p>W3CCredential</p> <ul> <li>class methods (<code>create</code>, <code>load</code>)</li> <li>instance methods (<code>process</code>, <code>to_legacy</code>, <code>add_non_anoncreds_integrity_proof</code>, <code>set_id</code>, <code>set_subject_id</code>, <code>add_context</code>, <code>add_type</code>)</li> <li>class properties (<code>schema_id</code>, <code>cred_def_id</code>, <code>rev_reg_id</code>, <code>rev_reg_index</code>)</li> <li>bindings functions (<code>create_w3c_credential</code>, <code>process_w3c_credential</code>, <code>_object_from_json</code>, <code>_object_get_attribute</code>, <code>w3c_credential_add_non_anoncreds_integrity_proof</code>, <code>w3c_credential_set_id</code>, <code>w3c_credential_set_subject_id</code>, <code>w3c_credential_add_context</code>, <code>w3c_credential_add_type</code>)</li> </ul> <p>W3CPresentation</p> <ul> <li>class methods (<code>create</code>, <code>load</code>)</li> <li>instance methods (<code>verify</code>)</li> <li>bindings functions (<code>create_w3c_presentation</code>, <code>_object_from_json</code>, <code>verify_w3c_presentation</code>)</li> </ul> <p>They will be added to __init__.py as additional exports of AnoncredsObject.</p> <p>We also have to consider which classes or anoncreds objects have been modified</p> <p>The classes modified according to the same PR mentioned above are:</p> <p>Credential</p> <ul> <li>added class methods (<code>from_w3c</code>)</li> <li>added instance methods (<code>to_w3c</code>)</li> <li>added bindings functions (<code>credential_from_w3c</code>, <code>credential_to_w3c</code>)</li> </ul> <p>PresentCredential</p> <ul> <li>modified instance methods (<code>_get_entry</code>, <code>add_attributes</code>, <code>add_predicates</code>)</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#creating-a-w3c-vc-credential-from-credential-definition-and-issuing-and-presenting-it-as-is","title":"Creating a W3C VC credential from credential definition, and issuing and presenting it as is","text":"<p>The issuance, presentation and verification of legacy anoncreds are implemented in this ./aries_cloudagent/anoncreds directory. Therefore, we will also start from there.</p> <p>Let us navigate these implementation examples through the respective processes of the concerning agents - Issuer and Holder as described in https://github.com/hyperledger/anoncreds-rs/blob/main/README.md. We will proceed through the following processes in comparison with the legacy anoncreds implementations while watching out for signature differences between the two. Looking at the /anoncreds/issuer.py file, from <code>AnonCredsIssuer</code> class:</p> <p>Create VC_DI Credential Offer</p> <p>According to this DI credential offer attachment format - didcomm/w3c-di-vc-offer@v0.1,</p> <ul> <li>binding_required</li> <li>binding_method</li> <li>credential_definition</li> </ul> <p>could be the parameters for <code>create_offer</code> method.</p> <p>Create VC_DI Credential</p> <p>NOTE: There has been some changes to encoding of attribute values for creating a credential, so we have to be adjust to the new changes.</p> <pre><code>async def create_credential(\n        self,\n        credential_offer: dict,\n        credential_request: dict,\n        credential_values: dict,\n    ) -&gt; str:\n...\n...\n  try:\n    credential = await asyncio.get_event_loop().run_in_executor(\n        None,\n        lambda: W3CCredential.create(\n            cred_def.raw_value,\n            cred_def_private.raw_value,\n            credential_offer,\n            credential_request,\n            raw_values,\n            None,\n            None,\n            None,\n            None,\n        ),\n    )\n...\n</code></pre> <p>Create VC_DI Credential Request</p> <pre><code>async def create_vc_di_credential_request(\n        self, credential_offer: dict, credential_definition: CredDef, holder_did: str\n    ) -&gt; Tuple[str, str]:\n...\n...\ntry:\n  secret = await self.get_master_secret()\n  (\n      cred_req,\n      cred_req_metadata,\n  ) = await asyncio.get_event_loop().run_in_executor(\n      None,\n      W3CCredentialRequest.create,\n      None,\n      holder_did,\n      credential_definition.to_native(),\n      secret,\n      AnonCredsHolder.MASTER_SECRET_ID,\n      credential_offer,\n  )\n...\n</code></pre> <p>Create VC_DI Credential Presentation</p> <pre><code>async def create_vc_di_presentation(\n        self,\n        presentation_request: dict,\n        requested_credentials: dict,\n        schemas: Dict[str, AnonCredsSchema],\n        credential_definitions: Dict[str, CredDef],\n        rev_states: dict = None,\n    ) -&gt; str:\n...\n...\n  try:\n    secret = await self.get_master_secret()\n    presentation = await asyncio.get_event_loop().run_in_executor(\n        None,\n        Presentation.create,\n        presentation_request,\n        present_creds,\n        self_attest,\n        secret,\n        {\n            schema_id: schema.to_native()\n            for schema_id, schema in schemas.items()\n        },\n        {\n            cred_def_id: cred_def.to_native()\n            for cred_def_id, cred_def in credential_definitions.items()\n        },\n    )\n...\n</code></pre>"},{"location":"design/AnoncredsW3CCompatibility/#converting-an-already-issued-legacy-anoncreds-to-vc_di-formatvice-versa","title":"Converting an already issued legacy anoncreds to VC_DI format(vice versa)","text":"<p>In this case, we can use <code>to_w3c</code> method of <code>Credential</code> class to convert from legacy to w3c and <code>to_legacy</code> method of <code>W3CCredential</code> class to convert from w3c to legacy.</p> <p>We could call <code>to_w3c</code> method like this:</p> <pre><code>vc_di_cred = Credential.to_w3c(cred_def)\n</code></pre> <p>and for <code>to_legacy</code>:</p> <pre><code>legacy_cred = W3CCredential.to_legacy()\n</code></pre> <p>We don't need to input any parameters to it as it in turn calls <code>Credential.from_w3c()</code> method under the hood.</p>"},{"location":"design/AnoncredsW3CCompatibility/#format-handler-for-issue_credential-v2_0-protocol","title":"Format Handler for Issue_credential V2_0 Protocol","text":"<p>Keeping in mind that we are trying to create anoncreds(not another type of VC) in w3c format, what if we add a protocol-level vc_di format support by adding a new format <code>VC_DI</code> in <code>./protocols/issue_credential/v2_0/messages/cred_format.py</code> -</p> <pre><code># /protocols/issue_credential/v2_0/messages/cred_format.py\n\nclass Format(Enum):\n    \u201c\u201d\u201dAttachment Format\u201d\u201d\u201d\n    INDY = FormatSpec(...)\n    LD_PROOF = FormatSpec(...)\n    VC_DI = FormatSpec(\n        \u201cvc_di/\u201d,\n        CredExRecordVCDI,\n        DeferLoad(\n            \u201caries_cloudagent.protocols.issue_credential.v2_0\u201d\n            \u201c.formats.vc_di.handler.AnonCredsW3CFormatHandler\u201d\n        ),\n    )\n</code></pre> <p>And create a new CredExRecordVCDI in reference to V20CredExRecordLDProof</p> <pre><code># /protocols/issue_credential/v2_0/models/detail/w3c.py\n\nclass CredExRecordW3C(BaseRecord):\n    \"\"\"Credential exchange W3C detail record.\"\"\"\n\n    class Meta:\n        \"\"\"CredExRecordW3C metadata.\"\"\"\n\n        schema_class = \"CredExRecordW3CSchema\"\n\n    RECORD_ID_NAME = \"cred_ex_w3c_id\"\n    RECORD_TYPE = \"w3c_cred_ex_v20\"\n    TAG_NAMES = {\"~cred_ex_id\"} if UNENCRYPTED_TAGS else {\"cred_ex_id\"}\n    RECORD_TOPIC = \"issue_credential_v2_0_w3c\"\n</code></pre> <p>Based on the proposed credential attachment format with the new Data Integrity proof in aries-rfcs 809 -</p> <pre><code>{\n  \"@id\": \"284d3996-ba85-45d9-964b-9fd5805517b6\",\n  \"@type\": \"https://didcomm.org/issue-credential/2.0/issue-credential\",\n  \"comment\": \"&lt;some comment&gt;\",\n  \"formats\": [\n    {\n      \"attach_id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n      \"format\": \"didcomm/w3c-di-vc@v0.1\"\n    }\n  ],\n  \"credentials~attach\": [\n    {\n      \"@id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n      \"mime-type\": \"application/ld+json\",\n      \"data\": {\n        \"base64\": \"ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0=\"\n      }\n    }\n  ]\n}\n</code></pre> <p>Assuming <code>VCDIDetail</code> and <code>VCDIOptions</code> are already in place, <code>VCDIDetailSchema</code> can be created like so:</p> <pre><code># /protocols/issue_credential/v2_0/formats/vc_di/models/cred_detail.py\n\nclass VCDIDetailSchema(BaseModelSchema):\n    \"\"\"VC_DI verifiable credential detail schema.\"\"\"\n\n    class Meta:\n        \"\"\"Accept parameter overload.\"\"\"\n\n        unknown = INCLUDE\n        model_class = VCDIDetail\n\n    credential = fields.Nested(\n        CredentialSchema(),\n        required=True,\n        metadata={\n            \"description\": \"Detail of the VC_DI Credential to be issued\",\n            \"example\": {\n                \"@id\": \"284d3996-ba85-45d9-964b-9fd5805517b6\",\n                \"@type\": \"https://didcomm.org/issue-credential/2.0/issue-credential\",\n                \"comment\": \"&lt;some comment&gt;\",\n                \"formats\": [\n                    {\n                        \"attach_id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n                        \"format\": \"didcomm/w3c-di-vc@v0.1\"\n                    }\n                ],\n                \"credentials~attach\": [\n                    {\n                        \"@id\": \"5b38af88-d36f-4f77-bb7a-2f04ab806eb8\",\n                        \"mime-type\": \"application/ld+json\",\n                        \"data\": {\n                            \"base64\": \"ewogICAgICAgICAgIkBjb250ZXogWwogICAgICAg...(clipped)...RNVmR0SXFXZhWXgySkJBIgAgfQogICAgICAgIH0=\"\n                        }\n                    }\n                ]\n            }\n        },\n    )\n</code></pre> <p>Then create w3c format handler with mapping like so:</p> <pre><code># /protocols/issue_credential/v2_0/formats/w3c/handler.py\n\nmapping = {\n            CRED_20_PROPOSAL: VCDIDetailSchema,\n            CRED_20_OFFER: VCDIDetailSchema,\n            CRED_20_REQUEST: VCDIDetailSchema,\n            CRED_20_ISSUE: VerifiableCredentialSchema,\n        }\n</code></pre> <p>Doing so would allow us to be more independent in defining the schema suited for anoncreds in w3c format and once the proposal protocol can handle the w3c format, probably the rest of the flow can be easily implemented by adding <code>vc_di</code> flag to the corresponding routes.</p>"},{"location":"design/AnoncredsW3CCompatibility/#admin-api-attachments","title":"Admin API Attachments","text":"<p>To make sure that once an endpoint has been called to trigger the <code>Issue Credential</code> flow in <code>0809 W3C_DI attachment formats</code> the subsequent endpoints also follow this format, we can keep track of this ATTACHMENT_FORMAT dictionary with the proposed <code>VC_DI</code> format.</p> <pre><code># Format specifications\nATTACHMENT_FORMAT = {\n    CRED_20_PROPOSAL: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred-filter@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc-detail@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di-detail@v2.0\",\n    },\n    CRED_20_OFFER: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred-abstract@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc-detail@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di-detail@v2.0\",\n    },\n    CRED_20_REQUEST: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred-req@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc-detail@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di-detail@v2.0\",\n    },\n    CRED_20_ISSUE: {\n        V20CredFormat.Format.INDY.api: \"hlindy/cred@v2.0\",\n        V20CredFormat.Format.LD_PROOF.api: \"aries/ld-proof-vc@v1.0\",\n        V20CredFormat.Format.VC_DI.api: \"aries/vc-di@v2.0\",\n    },\n}\n</code></pre> <p>And this _formats_filter function takes care of keeping the attachment formats uniform across the iteration of the flow. We can see this function gets called in:</p> <ul> <li>_create_free_offer function that gets called in the handler function of <code>/issue-credential-2.0/send-offer</code> route (in addition to other offer routes)</li> <li>credential_exchange_send_free_request handler function of <code>/issue-credential-2.0/send-request</code> route</li> <li>credential_exchange_create handler function of <code>/issue-credential-2.0/create</code> route</li> <li>credential_exchange_send handler function of <code>/issue-credential-2.0/send</code> route</li> </ul> <p>The same goes for ATTACHMENT_FORMAT of <code>Present Proof</code> flow. In this case, DIF Presentation Exchange formats in these test vectors that are influenced by RFC 0510 DIF Presentation Exchange will be implemented. Here, the _formats_attach function is the key for the same purpose above. It gets called in:</p> <ul> <li>present_proof_send_proposal handler function of <code>/present-proof-2.0/send-proposal</code> route</li> <li>present_proof_create_request handler function of <code>/present-proof-2.0/create-request</code> route</li> <li>present_proof_send_free_request handler function of <code>/present-proof-2.0/send-request</code> route</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#credential-exchange-admin-routes","title":"Credential Exchange Admin Routes","text":"<ul> <li>/issue-credential-2.0/create-offer</li> </ul> <p>This route indirectly calls <code>_formats_filters</code> function to create credential proposal, which is in turn used to create a credential offer in the filter format. The request body for this route might look like this:</p> <pre><code>{\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-issue\": true,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n            ...\n            ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/create</li> </ul> <p>This route indirectly calls <code>_format_result_with_details</code> function to generate a cred_ex_record in the specified format, which is then returned. The request body for this route might look like this:</p> <pre><code>{\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-remove\": true,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/send</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"connection_id\": &lt;connection_id&gt;,\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/send-offer</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"connection_id\": &lt;connection_id&gt;,\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-issue\": true,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"holder_did\": &lt;holder_did&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre> <ul> <li>/issue-credential-2.0/send-request</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"connection_id\": &lt;connection_id&gt;,\n    \"filter\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-remove\": true,\n    \"replacement_id\": &lt;replacement_id&gt;,\n    \"holder_did\": &lt;holder_did&gt;,\n    \"credential_preview\": {\n        \"@type\": \"issue-credential/2.0/credential-preview\",\n        \"attributes\": {\n           ...\n           ...\n        }\n    }\n}\n</code></pre>"},{"location":"design/AnoncredsW3CCompatibility/#presentation-admin-routes","title":"Presentation Admin Routes","text":"<ul> <li>/present-proof-2.0/send-proposal</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    ...\n    ...\n    \"connection_id\": &lt;connection_id&gt;,\n    \"presentation_proposal\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-present\": true,\n    \"auto-remove\": true,\n    \"trace\": false\n}\n</code></pre> <ul> <li>/present-proof-2.0/create-request</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    ...\n    ...\n    \"connection_id\": &lt;connection_id&gt;,\n    \"presentation_proposal\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-verify\": true,\n    \"auto-remove\": true,\n    \"trace\": false\n}\n</code></pre> <ul> <li>/present-proof-2.0/send-request</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    ...\n    ...\n    \"connection_id\": &lt;connection_id&gt;,\n    \"presentation_proposal\": [\"vc_di\"],\n    \"comment: &lt;some_comment&gt;,\n    \"auto-verify\": true,\n    \"auto-remove\": true,\n    \"trace\": false\n}\n</code></pre> <ul> <li>/present-proof-2.0/records/{pres_ex_id}/send-presentation</li> </ul> <p>The request body for this route might look like this:</p> <pre><code>{\n    \"presentation_definition\": &lt;presentation_definition_schema&gt;,\n    \"auto_remove\": true,\n    \"dif\": {\n        issuer_id: \"&lt;issuer_id&gt;\",\n        record_ids: {\n            \"&lt;input descriptor id_1&gt;\": [\"&lt;record id_1&gt;\", \"&lt;record id_2&gt;\"],\n            \"&lt;input descriptor id_2&gt;\": [\"&lt;record id&gt;\"],\n        }\n    },\n    \"reveal_doc\": {\n        // vc_di dict\n    }\n\n}\n</code></pre>"},{"location":"design/AnoncredsW3CCompatibility/#how-a-w3c-credential-is-stored-in-the-wallet","title":"How a W3C credential is stored in the wallet","text":"<p>Storing a credential in the wallet is somewhat dependent on the kinds of metadata that are relevant. The metadata mapping between the W3C credential and an AnonCreds credential is not fully clear yet.</p> <p>One of the questions we need to answer is whether the preferred approach is to modify the existing store credential function so that any credential type is a valid input, or whether there should be a special function just for storing W3C credentials.</p> <p>We will duplicate this store_credential function and modify it:</p> <pre><code>async def store_w3c_credential(...) {\n    ...\n    ...\n    try:\n        cred = W3CCredential.load(credential_data)\n    ...\n    ...\n}\n</code></pre> <p>Question: Would it also be possible to generate the credentials on the fly to eliminate the need for storage?</p> <p>Answer: I don't think it is possible to eliminate the need for storage, and notably the secure storage (encrypted at rest) supported in Askar.</p>"},{"location":"design/AnoncredsW3CCompatibility/#how-can-we-handle-multiple-signatures-on-a-w3c-vc-format-credential","title":"How can we handle multiple signatures on a W3C VC Format credential?","text":"<p>Only one of the signature types (CL) is allowed in the AnonCreds format, so if a W3C VC is created by <code>to_legacy()</code>, all signature types that can't be turned into a CL signature will be dropped. This would make the conversion lossy. Similarly, an AnonCreds credential carries only the CL signature, limiting output from <code>to_w3c()</code> signature types that can be derived from the source CL signature. A possible future enhancement would be to add an extra field to the AnonCreds data structure, in which additional signatures could be stored, even if they are not used. This could eliminate the lossiness, but it adds extra complexity and may not be worth doing.</p> <ul> <li>Unlike a \"typical\" non-AnonCreds W3C VC, an AnonCreds VC is never directly presented to a verifier. Rather, a derivation of the credential is generated, and it is the derivation that is shared with the verifier as a presentation. The derivation:</li> <li>Generates presentation-specific signatures to be verified.</li> <li>Selectively reveals attributes.</li> <li>Generates proofs of the requested predicates.</li> <li>Generates a proof of knowledge of the link secret blinded in the verifiable credential.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#compatibility-with-afj-how-can-we-make-sure-that-we-are-compatible","title":"Compatibility with AFJ: how can we make sure that we are compatible?","text":"<p>We will write a test for the Aries Agent Test Framework that issues a W3C VC instead of an AnonCreds credential, and then run that test where one of the agents is ACA-PY and the other is based on AFJ -- and vice versa. Also write a test where a W3C VC is presented after an AnonCreds issuance, and run it with the two roles played by the two different agents. This is a simple approach, but if the tests pass, this should eliminate almost all risk of incompatibility.</p>"},{"location":"design/AnoncredsW3CCompatibility/#will-we-introduce-new-dependencies-and-what-is-risky-or-easy","title":"Will we introduce new dependencies, and what is risky or easy?","text":"<p>Any significant bugs in the Rust implementation may prevent our wrappers from working, which would also prevent progress (or at least confirmed test results) on the higher-level code.</p> <p>If AFJ lags behind in delivering equivalent functionality, we may not be able to demonstrate compatibility with the test harness.</p>"},{"location":"design/AnoncredsW3CCompatibility/#where-should-the-new-issuance-code-go","title":"Where should the new issuance code go?","text":"<p>So the vc directory contains code to verify vc's, is this a logical place to add the code for issuance?</p>"},{"location":"design/AnoncredsW3CCompatibility/#what-do-we-call-the-new-things-flexcreds-or-just-w3c_xxx","title":"What do we call the new things? Flexcreds? or just W3C_xxx","text":"<p>Are we defining a concept called Flexcreds that is a credential with a proof array that you can generate more specific or limited credentials from? If so should this be included in the naming?</p> <ul> <li>I don't think naming comes into play. We are creating and deriving presentations from VC Data Integrity Proofs using an AnonCreds cryptosuite. As such, these are \"stock\" W3C verifiable credentials.</li> </ul>"},{"location":"design/AnoncredsW3CCompatibility/#how-can-a-wallet-retain-the-capability-to-present-only-an-anoncred-credential","title":"How can a wallet retain the capability to present ONLY an anoncred credential?","text":"<p>If the wallet receives a \"Flexcred\" credential object with an array of proofs, the wallet may wish to present ONLY the more zero-knowledge anoncreds proof</p> <p>How will wallets support that in a way that is developer-friendly to wallet devs?</p> <ul> <li>The trigger for wallets to generate a W3C VP Format presentation is that they have receive a RFC 0510 DIF Presentation Exchange that can be satisfied with an AnonCreds verifiable credential in their storage. Once we decide to use one or more AnonCreds VCs to satisfy a presentation, we'll derive such a presentation and send it using the RFC 0510 DIF Presentation Exchange for the <code>presentation</code> message of the Present Proof v2.0 protocol.</li> </ul>"},{"location":"features/AdminAPI/","title":"ACA-Py Administration API","text":""},{"location":"features/AdminAPI/#using-the-openapi-swagger-interface","title":"Using the OpenAPI (Swagger) Interface","text":"<p>ACA-Py provides an OpenAPI-documented REST interface for administering the agent's internal state and initiating communication with connected agents.</p> <p>To see the specifics of the supported endpoints, as well as the expected request and response formats, it is recommended to run the <code>aca-py</code> agent with the <code>--admin {HOST} {PORT}</code> and <code>--admin-insecure-mode</code> command line parameters. This exposes the OpenAPI UI on the provided port for interaction via a web browser. For production deployments, run the agent with <code>--admin-api-key {KEY}</code> and add the <code>X-API-Key: {KEY}</code> header to all requests instead of using the <code>--admin-insecure-mode</code> parameter.</p> <p></p> <p>To invoke a specific method:</p> <ul> <li>Scroll to and find that endpoint;</li> <li>Click on the endpoint name to expand its section of the UI;</li> <li>Click on the Try it out button;</li> <li>Fill in any data necessary to run the command;</li> <li>Click Execute;</li> <li>Check the response to see if the request worked as expected.</li> </ul> <p>The mechanical steps are easy; however, the fourth step from the list above can be tricky. Supplying the right data and, where JSON is involved, getting the syntax correct\u2014braces and quotes can be a pain. When steps don't work, start your debugging by looking at your JSON. You may also choose to use a REST client like Postman or Insomnia, which will provide syntax highlighting and other features to simplify the process.</p> <p>Because API methods often initiate asynchronous processes, the JSON response provided by an endpoint is not always sufficient to determine the next action. To handle this situation, as well as events triggered by external inputs (such as new connection requests), it is necessary to implement a webhook processor, as detailed in the next section.</p> <p>The combination of an OpenAPI client and webhook processor is referred to as an ACA-Py Controller and is the recommended method to define custom behaviors for your ACA-Py-based agent application.</p>"},{"location":"features/AdminAPI/#administration-api-webhooks","title":"Administration API Webhooks","text":"<p>When ACA-Py is started with the <code>--webhook-url {URL}</code> command line parameter, state-management records are sent to the provided URL via POST requests whenever a record is created or its <code>state</code> property is updated.</p> <p>When a webhook is dispatched, the record <code>topic</code> is appended as a path component to the URL. For example, <code>https://webhook.host.example</code> becomes <code>https://webhook.host.example/topic/connections</code> when a connection record is updated. A POST request is made to the resulting URL with the body of the request comprising a serialized JSON object. The full set of properties of the current set of webhook payloads are listed below. Note that empty (null-value) properties are omitted.</p>"},{"location":"features/AdminAPI/#webhooks-over-websocket","title":"Webhooks over WebSocket","text":"<p>ACA-Py's Admin API also supports delivering webhooks over WebSocket. This can be especially useful when working with scripts that interact with the Admin API but don't have a web server listening to receive webhooks in response to its actions. No additional command line parameters are required to enable WebSocket support.</p> <p>Webhooks received over WebSocket will contain the same data as webhooks posted over http but the structure differs in order to communicate details that would have been received as part of the HTTP request path and headers.</p> <ul> <li><code>topic</code>: The topic of the webhook, such as <code>connections</code> or <code>basicmessages</code></li> <li><code>payload</code>: The payload of the webhook; this is the data usually received in the request body when webhooks are delivered over HTTP</li> <li><code>wallet_id</code>: If using multitenancy, this is the wallet ID of the subwallet that emitted the webhook. This value will be omitted if not using multitenancy.</li> </ul> <p>To open a WebSocket, connect to the <code>/ws</code> endpoint of the Admin API.</p>"},{"location":"features/AdminAPI/#pairwise-connection-record-updated-connections","title":"Pairwise Connection Record Updated (<code>/connections</code>)","text":"<ul> <li><code>connection_id</code>: the unique connection identifier</li> <li><code>state</code>: <code>init</code> / <code>invitation</code> / <code>request</code> / <code>response</code> / <code>active</code> / <code>error</code> / <code>inactive</code></li> <li><code>my_did</code>: the DID this agent is using in the connection</li> <li><code>their_did</code>: the DID the other agent in the connection is using</li> <li><code>their_label</code>: a connection label provided by the other agent</li> <li><code>their_role</code>: a role assigned to the other agent in the connection</li> <li><code>inbound_connection_id</code>: a connection identifier for the related inbound routing connection</li> <li><code>initiator</code>: <code>self</code> / <code>external</code> / <code>multiuse</code></li> <li><code>invitation_key</code>: a verification key used to identify the source connection invitation</li> <li><code>request_id</code>: the <code>@id</code> property from the connection request message</li> <li><code>routing_state</code>: <code>none</code> / <code>request</code> / <code>active</code> / <code>error</code></li> <li><code>accept</code>: <code>manual</code> / <code>auto</code></li> <li><code>error_msg</code>: the most recent error message</li> <li><code>invitation_mode</code>: <code>once</code> / <code>multi</code></li> <li><code>alias</code>: a local alias for the connection record</li> </ul>"},{"location":"features/AdminAPI/#basic-message-received-basicmessages","title":"Basic Message Received (<code>/basicmessages</code>)","text":"<ul> <li><code>connection_id</code>: the identifier of the related pairwise connection</li> <li><code>message_id</code>: the <code>@id</code> of the incoming agent message</li> <li><code>content</code>: the contents of the agent message</li> <li><code>state</code>: <code>received</code></li> </ul>"},{"location":"features/AdminAPI/#forward-message-received-forward","title":"Forward Message Received  (<code>/forward</code>)","text":"<p>Enable using <code>--monitor-forward</code>.</p> <ul> <li><code>connection_id</code>: the identifier of the connection associated with the recipient key</li> <li><code>recipient_key</code>: the recipient key of the forward message (<code>to</code> field of the forward message)</li> <li><code>status</code>: The delivery status of the received forward message. Possible values:</li> <li><code>sent_to_session</code>: Message is sent directly to the connection over an active transport session</li> <li><code>sent_to_external_queue</code>: Message is sent to an external queue. No information is known on the delivery of the message</li> <li><code>queued_for_delivery</code>: Message is queued for delivery using outbound transport (recipient connection has an endpoint)</li> <li><code>waiting_for_pickup</code>: The connection has no reachable endpoint. Need to wait for the recipient to connect with return routing for delivery</li> <li><code>undeliverable</code>: The connection has no reachable endpoint, and the internal queue for messages is not enabled (<code>--enable-undelivered-queue</code>).</li> </ul>"},{"location":"features/AdminAPI/#credential-exchange-record-updated-issue_credential","title":"Credential Exchange Record Updated (<code>/issue_credential</code>)","text":"<ul> <li><code>credential_exchange_id</code>: the unique identifier of the credential exchange</li> <li><code>connection_id</code>: the identifier of the related pairwise connection</li> <li><code>thread_id</code>: the thread ID of the previously received credential proposal or offer</li> <li><code>parent_thread_id</code>: the parent thread ID of the previously received credential proposal or offer</li> <li><code>initiator</code>: issue-credential exchange initiator <code>self</code> / <code>external</code></li> <li><code>state</code>: <code>proposal_sent</code> / <code>proposal_received</code> / <code>offer_sent</code> / <code>offer_received</code> / <code>request_sent</code> / <code>request_received</code> / <code>issued</code> / <code>credential_received</code> / <code>credential_acked</code></li> <li><code>credential_definition_id</code>: the ledger identifier of the related credential definition</li> <li><code>schema_id</code>: the ledger identifier of the related credential schema</li> <li><code>credential_proposal_dict</code>: the credential proposal message</li> <li><code>credential_offer</code>: (Indy) credential offer</li> <li><code>credential_request</code>: (Indy) credential request</li> <li><code>credential_request_metadata</code>: (Indy) credential request metadata</li> <li><code>credential_id</code>: the wallet identifier of the stored credential</li> <li><code>raw_credential</code>: the credential record as received</li> <li><code>credential</code>: the credential record as stored in the wallet</li> <li><code>auto_offer</code>: (boolean) whether to automatically offer the credential</li> <li><code>auto_issue</code>: (boolean) whether to automatically issue the credential</li> <li><code>error_msg</code>: the previous error message</li> </ul>"},{"location":"features/AdminAPI/#presentation-exchange-record-updated-present_proof","title":"Presentation Exchange Record Updated (<code>/present_proof</code>)","text":"<ul> <li><code>presentation_exchange_id</code>: the unique identifier of the presentation exchange</li> <li><code>connection_id</code>: the identifier of the related pairwise connection</li> <li><code>thread_id</code>: the thread ID of the previously received presentation proposal or offer</li> <li><code>initiator</code>: present-proof exchange initiator: <code>self</code> / <code>external</code></li> <li><code>state</code>: <code>proposal_sent</code> / <code>proposal_received</code> / <code>request_sent</code> / <code>request_received</code> / <code>presentation_sent</code> / <code>presentation_received</code> / <code>verified</code></li> <li><code>presentation_proposal_dict</code>: the presentation proposal message</li> <li><code>presentation_request</code>: (Indy) presentation request (also known as proof request)</li> <li><code>presentation</code>: (Indy) presentation (also known as proof)</li> <li><code>verified</code>: (string) whether the presentation is verified: <code>true</code> or <code>false</code></li> <li><code>auto_present</code>: (boolean) prover choice to auto-present proof as verifier requests</li> <li><code>error_msg</code>: the previous error message</li> </ul>"},{"location":"features/AdminAPI/#api-standard-behavior","title":"API Standard Behavior","text":"<p>The best way to develop a new admin API or protocol is to follow one of the existing protocols, such as the Credential Exchange or Presentation Exchange.</p> <p>The <code>routes.py</code> file contains the API definitions - API endpoints and payload schemas (note that these are not the Aries message schemas).</p> <p>The payload schemas are defined using marshmallow and will be validated automatically when the API is executed (using middleware). (This raises a status <code>422</code> HTTP response with an error message if the schema validation fails.)</p> <p>API endpoints are defined using aiohttp_apispec tags (e.g. <code>@doc</code>, <code>@request_schema</code>, <code>@response_schema</code> etc.) which define the input and output parameters of the endpoint. API URL paths are defined in the <code>register()</code> method and added to the Swagger page in the <code>post_process_routes()</code> method.</p> <p>The APIs should return the following HTTP status:</p> <ul> <li>HTTP 200 for successful API completion, with an appropriate response</li> <li>HTTP 400 (or appropriate 4xx code) (with an error message) for errors on input parameters (i.e., the user can retry with different parameters and potentially get a successful API call)</li> <li>HTTP 404 if a record is expected and not found (generally for GET requests that fetch a single record)</li> <li>HTTP 500 (or appropriate 5xx code) if there is some other processing error (i.e., it won't make any difference what parameters the user tries) with an error message</li> </ul> <p>...and should not return:</p> <ul> <li>HTTP 500 with a stack trace due to an untrapped error (we should handle error conditions with a 400 or 404 response and catch errors, providing a meaningful error message)</li> </ul>"},{"location":"features/AnoncredsProofValidation/","title":"Anoncreds Proof Validation in ACA-Py","text":"<p>ACA-Py performs pre-validation when verifying Anoncreds presentations (proofs). Some scenarios are rejected (such as those indicative of tampering), while some attributes are removed before running the anoncreds validation (e.g., removing superfluous non-revocation timestamps). Any ACA-Py validations or presentation modifications are indicated by the \"verify_msgs\" attribute in the final presentation exchange object.</p> <p>The list of possible verification messages can be found here, and consists of:</p> <pre><code>class PresVerifyMsg(str, Enum):\n    \"\"\"Credential verification codes.\"\"\"\n\n    RMV_REFERENT_NON_REVOC_INTERVAL = \"RMV_RFNT_NRI\"\n    RMV_GLOBAL_NON_REVOC_INTERVAL = \"RMV_GLB_NRI\"\n    TSTMP_OUT_NON_REVOC_INTRVAL = \"TS_OUT_NRI\"\n    CT_UNREVEALED_ATTRIBUTES = \"UNRVL_ATTR\"\n    PRES_VALUE_ERROR = \"VALUE_ERROR\"\n    PRES_VERIFY_ERROR = \"VERIFY_ERROR\"\n</code></pre> <p>If there is additional information, it will be included like this: <code>TS_OUT_NRI::19_uuid</code> (which means the attribute identified by <code>19_uuid</code> contained a timestamp outside of the non-revocation interval (this is just a warning)).</p> <p>A presentation verification may include multiple messages, for example:</p> <pre><code>    ...\n    \"verified\": \"true\",\n    \"verified_msgs\": [\n        \"TS_OUT_NRI::18_uuid\",\n        \"TS_OUT_NRI::18_id_GE_uuid\",\n        \"TS_OUT_NRI::18_busid_GE_uuid\"\n    ],\n    ...\n</code></pre> <p>... or it may include a single message, for example:</p> <pre><code>    ...\n    \"verified\": \"false\",\n    \"verified_msgs\": [\n        \"VALUE_ERROR::Encoded representation mismatch for 'Preferred Name'\"\n    ],\n    ...\n</code></pre> <p>... or the <code>verified_msgs</code> may be null or an empty array.</p>"},{"location":"features/AnoncredsProofValidation/#presentation-modifications-and-warnings","title":"Presentation Modifications and Warnings","text":"<p>The following modifications/warnings may be made by ACA-Py, which shouldn't affect the verification of the received proof:</p> <ul> <li>\"RMV_RFNT_NRI\": Referent contains a non-revocation interval for a non-revocable credential (timestamp is removed)</li> <li>\"RMV_GLB_NRI\": Presentation contains a global interval for a non-revocable credential (timestamp is removed)</li> <li>\"TS_OUT_NRI\": Presentation contains a non-revocation timestamp outside of the requested non-revocation interval (warning)</li> <li>\"UNRVL_ATTR\": Presentation contains attributes with unrevealed values (warning)</li> </ul>"},{"location":"features/AnoncredsProofValidation/#presentation-pre-validation-errors","title":"Presentation Pre-validation Errors","text":"<p>The following pre-verification checks are performed, which will cause the proof to fail (before calling anoncreds) and result in the following message:</p> <pre><code>VALUE_ERROR::&lt;description of the failed validation&gt;\n</code></pre> <p>These validations are all performed within the Indy verifier class - to see the detailed validation, look for any occurrences of <code>raise ValueError(...)</code> in the code.</p> <p>A summary of the possible errors includes:</p> <ul> <li>Information missing in presentation exchange record</li> <li>Timestamp provided for irrevocable credential</li> <li>Referenced revocation registry not found on ledger</li> <li>Timestamp outside of reasonable range (future date or pre-dates revocation registry)</li> <li>Mismatch between provided and requested timestamps for non-revocation</li> <li>Mismatch between requested and provided attributes or predicates</li> <li>Self-attested attribute provided for a requested attribute with restrictions</li> <li>Encoded value doesn't match raw value</li> </ul>"},{"location":"features/AnoncredsProofValidation/#anoncreds-verification-exceptions","title":"Anoncreds Verification Exceptions","text":"<p>Typically, when you call the anoncreds <code>verifier_verify_proof()</code> method, it will return a <code>True</code> or <code>False</code> based on whether the presentation cryptographically verifies. However, in the case where anoncreds throws an exception, the exception text will be included in a verification message as follows:</p> <pre><code>VERIFY_ERROR::&lt;the exception text&gt;\n</code></pre>"},{"location":"features/DIDMethods/","title":"DID Methods in ACA-Py","text":"<p>Decentralized Identifiers, or DIDs, are URIs that point to documents that describe cryptographic primitives and protocols used in decentralized identity management. DIDs include methods that describe where and how documents can be retrieved. DID methods support specific types of keys and may or may not require the holder to specify the DID itself.</p> <p>ACA-Py provides a <code>DIDMethods</code> registry holding all the DID methods supported for storage in a wallet</p> <p> Askar and InMemory are the only wallets supporting this registry.</p>"},{"location":"features/DIDMethods/#registering-a-did-method","title":"Registering a DID method","text":"<p>By default, ACA-Py supports <code>did:key</code> and <code>did:sov</code>. Plugins can register DID additional methods to make them available to holders. Here's a snippet adding support for <code>did:web</code> to the registry from a plugin <code>setup</code> method.</p> <pre><code>WEB = DIDMethod(\n    name=\"web\",\n    key_types=[ED25519, BLS12381G2],\n    rotation=True,\n    holder_defined_did=HolderDefinedDid.REQUIRED  # did:web is not derived from key material but from a user-provided repository name\n)\n\nasync def setup(context: InjectionContext):\n    methods = context.inject(DIDMethods)\n    methods.register(WEB)\n</code></pre>"},{"location":"features/DIDMethods/#creating-a-did","title":"Creating a DID","text":"<p><code>POST /wallet/did/create</code> can be provided with parameters for any registered DID method. Here's a follow-up to the <code>did:web</code> method example:</p> <pre><code>{\n    \"method\": \"web\",\n    \"options\": {\n        \"did\": \"did:web:doma.in\",\n        \"key_type\": \"ed25519\"\n    }\n}\n</code></pre>"},{"location":"features/DIDMethods/#resolving-dids","title":"Resolving DIDs","text":"<p>For specifics on how DIDs are resolved in ACA-Py, see: DID Resolution.</p>"},{"location":"features/DIDResolution/","title":"DID Resolution in ACA-Py","text":"<p>Decentralized Identifiers, or DIDs, are URIs that point to documents that describe cryptographic primitives and protocols used in decentralized identity management. DIDs include methods that describe where and how documents can be retrieved. DID resolution is the process of \"resolving\" a DID Document from a DID as dictated by the DID method.</p> <p>A DID Resolver is a piece of software that implements the methods for resolving a document from a DID.</p> <p>For example, given the DID <code>did:example:1234abcd</code>, a DID Resolver that supports <code>did:example</code> might return:</p> <pre><code>{\n \"@context\": \"https://www.w3.org/ns/did/v1\",\n \"id\": \"did:example:1234abcd\",\n \"verificationMethod\": [{\n  \"id\": \"did:example:1234abcd#keys-1\",\n  \"type\": \"Ed25519VerificationKey2018\",\n  \"controller\": \"did:example:1234abcd\",\n  \"publicKeyBase58\": \"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"\n }],\n \"service\": [{\n  \"id\": \"did:example:1234abcd#did-communication\",\n  \"type\": \"did-communication\",\n  \"serviceEndpoint\": \"https://agent.example.com/8377464\"\n }]\n}\n</code></pre> <p>For more details on DIDs and DID Resolution, see the W3C DID Specification.</p> <p>In practice, DIDs and DID Documents are used for a variety of purposes but especially to help establish connections between Agents and verify credentials.</p>"},{"location":"features/DIDResolution/#didresolver","title":"<code>DIDResolver</code>","text":"<p>In ACA-Py, the <code>DIDResolver</code> provides the interface to resolve DIDs using registered method resolvers. Method resolver registration happens on startup in a <code>did_resolvers</code> list. This registry enables additional resolvers to be loaded via plugin.</p>"},{"location":"features/DIDResolution/#example-usage","title":"Example usage","text":"<pre><code>class ExampleMessageHandler:\n    async def handle(context: RequestContext, responder: BaseResponder):\n    \"\"\"Handle example message.\"\"\"\n    resolver = await context.inject(DIDResolver)\n\n    doc: dict = await resolver.resolve(\"did:example:123\")\n    assert doc[\"id\"] == \"did:example:123\"\n\n    verification_method = await resolver.dereference(\"did:example:123#keys-1\")\n\n    # ...\n</code></pre>"},{"location":"features/DIDResolution/#method-resolver-selection","title":"Method Resolver Selection","text":"<p>On <code>DIDResolver.resolve</code> or <code>DIDResolver.dereference</code>, the resolver interface will select the most appropriate method resolver to handle the given DID. In this selection process, method resolvers are distinguished from each other by:</p> <ul> <li>Type. The resolver's type falls into one of two categories: native or non-native. A \"native\" resolver will perform all resolution steps directly. A \"non-native\" resolver delegates all or part of resolution to another service or entity.</li> <li>Self-reported supported DIDs. Each method resolver implements a <code>supports</code> method or a <code>supported_did_regex</code> method. These methods are used to determine whether the given DID can be handled by the method resolver.</li> </ul> <p>The selection algorithm roughly follows the following steps:</p> <ol> <li>Filter out all resolvers where <code>resolver.supports(did)</code> returns <code>false</code>.</li> <li>Partition remaining resolvers by type with all native resolvers followed by non-native resolvers (registration order preserved within partitions).</li> <li>For each resolver in the resulting list, attempt to resolve the DID and return the first successful result.</li> </ol>"},{"location":"features/DIDResolution/#resolver-plugins","title":"Resolver Plugins","text":"<p>Extending ACA-Py with additional Method Resolvers should be relatively simple. Supposing that you want to resolve DIDs for the <code>did:cool</code> method, this should be as simple as installing a method resolver into your python environment and loading the resolver on startup. If no method resolver exists yet for <code>did:cool</code>, writing your own should require minimal overhead.</p>"},{"location":"features/DIDResolution/#writing-a-resolver-plugin","title":"Writing a resolver plugin","text":"<p>Method resolver plugins are composed of two primary pieces: plugin injection and resolution logic. The resolution logic dictates how a DID becomes a DID Document, following the given DID Method Specification. This logic is implemented using the <code>BaseDIDResolver</code> class as the base. <code>BaseDIDResolver</code> is an abstract base class that defines the interface that the core <code>DIDResolver</code> expects for Method resolvers.</p> <p>The following is an example method resolver implementation. In this example, we have 2 files, one for each piece (injection and resolution). The <code>__init__.py</code> will be in charge of injecting the plugin, and <code>example_resolver.py</code> will have the logic implementation to resolve for a fabricated <code>did:example</code> method.</p>"},{"location":"features/DIDResolution/#__init-__py","title":"<code>__init __.py</code>","text":"<p>```python= from aries_cloudagent.config.injection_context import InjectionContext from ..resolver.did_resolver import DIDResolver</p> <p>from .example_resolver import ExampleResolver</p> <p>async def setup(context: InjectionContext):     \"\"\"Setup the plugin.\"\"\"     registry = context.inject(DIDResolver)     resolver = ExampleResolver()     await resolver.setup(context)     registry.append(resolver) <pre><code>#### `example_resolver.py`\n\n```python=\nimport re\nfrom typing import Pattern\nfrom aries_cloudagent.resolver.base import BaseDIDResolver, ResolverType\n\nclass ExampleResolver(BaseDIDResolver):\n    \"\"\"ExampleResolver class.\"\"\"\n\n    def __init__(self):\n        super().__init__(ResolverType.NATIVE)\n        # Alternatively, ResolverType.NON_NATIVE\n        self._supported_did_regex = re.compile(\"^did:example:.*$\")\n\n    @property\n    def supported_did_regex(self) -&gt; Pattern:\n        \"\"\"Return compiled regex matching supported DIDs.\"\"\"\n        return self._supported_did_regex\n\n    async def setup(self, context):\n        \"\"\"Setup the example resolver (none required).\"\"\"\n\n    async def _resolve(self, profile: Profile, did: str) -&gt; dict:\n        \"\"\"Resolve example DIDs.\"\"\"\n        if did != \"did:example:1234abcd\":\n            raise DIDNotFound(\n                \"We only actually resolve did:example:1234abcd. Sorry!\"\n            )\n\n        return {\n            \"@context\": \"https://www.w3.org/ns/did/v1\",\n            \"id\": \"did:example:1234abcd\",\n            \"verificationMethod\": [{\n                \"id\": \"did:example:1234abcd#keys-1\",\n                \"type\": \"Ed25519VerificationKey2018\",\n                \"controller\": \"did:example:1234abcd\",\n                \"publicKeyBase58\": \"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"\n            }],\n            \"service\": [{\n                \"id\": \"did:example:1234abcd#did-communication\",\n                \"type\": \"did-communication\",\n                \"serviceEndpoint\": \"https://agent.example.com/\"\n            }]\n        }\n</code></pre></p>"},{"location":"features/DIDResolution/#errors","title":"Errors","text":"<p>There are 3 different errors associated with resolution in ACA-Py that could be used for development purposes.</p> <ul> <li>ResolverError</li> <li>Base class for resolver exceptions.</li> <li>DIDNotFound</li> <li>Raised when DID is not found using DID method specific algorithm.</li> <li>DIDMethodNotSupported</li> <li>Raised when no resolver is registered for a given did method.</li> </ul>"},{"location":"features/DIDResolution/#using-resolver-plugins","title":"Using Resolver Plugins","text":"<p>In this section, the Github Resolver Plugin found here will be used as an example plugin to work with. This resolver resolves <code>did:github</code> DIDs.</p> <p>The resolution algorithm is simple: for the github DID <code>did:github:dbluhm</code>, the method specific identifier <code>dbluhm</code> (a GitHub username) is used to lookup an <code>index.jsonld</code> file in the <code>ghdid</code> repository in that GitHub users profile. See GitHub DID Method Specification for more details.</p> <p>To use this plugin, first install it into your project's python environment:</p> <pre><code>pip install git+https://github.com/dbluhm/acapy-resolver-github\n</code></pre> <p>Then, invoke ACA-Py as you normally do with the addition of:</p> <pre><code>$ aca-py start \\\n    --plugin acapy_resolver_github \\\n    # ... the remainder of your startup arguments\n</code></pre> <p>Or add the following to your configuration file:</p> <pre><code>plugin:\n  - acapy_resolver_github\n</code></pre> <p>The following is a fully functional Dockerfile encapsulating this setup:</p> <p>```dockerfile= FROM ghcr.io/hyperledger/aries-cloudagent-python:py3.9-0.12.0rc2 RUN pip3 install git+https://github.com/dbluhm/acapy-resolver-github</p> <p>CMD [\"aca-py\", \"start\", \"-it\", \"http\", \"0.0.0.0\", \"3000\", \"-ot\", \"http\", \"-e\", \"http://localhost:3000\", \"--admin\", \"0.0.0.0\", \"3001\", \"--admin-insecure-mode\", \"--no-ledger\", \"--plugin\", \"acapy_resolver_github\"] <pre><code>To use the above dockerfile:\n\n```shell\ndocker build -t resolver-example .\ndocker run --rm -it -p 3000:3000 -p 3001:3001 resolver-example\n</code></pre></p>"},{"location":"features/DIDResolution/#directory-of-resolver-plugins","title":"Directory of Resolver Plugins","text":"<ul> <li>Github Resolver</li> <li>Universal Resolver</li> <li>DIDComm Resolver</li> </ul>"},{"location":"features/DIDResolution/#references","title":"References","text":"<p>https://www.w3.org/TR/did-core/ https://w3c-ccg.github.io/did-resolution/</p>"},{"location":"features/DevReadMe/","title":"Developer's Read Me for Hyperledger Aries Cloud Agent - Python","text":"<p>See the README for details about this repository and information about how the Aries Cloud Agent - Python fits into the Aries project and relates to Indy.</p>"},{"location":"features/DevReadMe/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Introduction</li> <li>Developer Demos</li> <li>Running</li> <li>Configuring ACA-PY: Command Line Parameters</li> <li>Docker</li> <li>Locally Installed</li> <li>About ACA-Py Command Line Parameters</li> <li>Provisioning Secure Storage</li> <li>Mediation</li> <li>Multi-tenancy</li> <li>JSON-LD Credentials</li> <li>Developing</li> <li>Prerequisites</li> <li>Running In A Dev Container</li> <li>Running Locally</li> <li>Logging</li> <li>Running Tests</li> <li>Running Aries Agent Test Harness Tests</li> <li>Development Workflow</li> <li>Publishing Releases</li> <li>Dynamic Injection of Services</li> </ul>"},{"location":"features/DevReadMe/#introduction","title":"Introduction","text":"<p>Aries Cloud Agent Python (ACA-Py) is a configurable, extensible, non-mobile Aries agent that implements an easy way for developers to build decentralized identity services that use verifiable credentials.</p> <p>The information on this page assumes you are developer with a background in decentralized identity, Aries, DID Methods, and verifiable credentials, especially AnonCreds. If you aren't familiar with those concepts and projects, please use our Getting Started Guide to learn more.</p>"},{"location":"features/DevReadMe/#developer-demos","title":"Developer Demos","text":"<p>To put ACA-Py through its paces at the command line, checkout our demos page.</p>"},{"location":"features/DevReadMe/#running","title":"Running","text":""},{"location":"features/DevReadMe/#configuring-aca-py-command-line-parameters","title":"Configuring ACA-PY: Command Line Parameters","text":"<p>ACA-Py agent instances are configured through the use of command line parameters, environment variables and/or YAML files. All of the configurations settings can be managed using any combination of the three methods (command line parameters override environment variables override YAML). Use the <code>--help</code> option to discover the available command line parameters. There are a lot of them--for good and bad.</p>"},{"location":"features/DevReadMe/#docker","title":"Docker","text":"<p>To run a docker container based on the code in the current repo, use the following commands from the root folder of the repository to check the version, list the available modes of operation, and see all of the command line parameters:</p> <pre><code>scripts/run_docker --version\nscripts/run_docker --help\nscripts/run_docker provision --help\nscripts/run_docker start --help\n</code></pre>"},{"location":"features/DevReadMe/#locally-installed","title":"Locally Installed","text":"<p>If you installed the PyPi package, the executable <code>aca-py</code> should be available on your PATH.</p> <p>Use the following commands from the root folder of the repository to check the version, list the available modes of operation, and see all of the command line parameters:</p> <pre><code>aca-py --version\naca-py --help\naca-py provision --help\naca-py start --help\n</code></pre> <p>If you get an error about a missing module <code>indy</code> (e.g. <code>ModuleNotFoundError: No module named 'indy'</code>) when running <code>aca-py</code>, you will need to install the Indy libraries from the command line:</p> <pre><code>pip install python3_indy\n</code></pre> <p>Once that completes successfully, you should be able to run <code>aca-py --version</code> and the other examples above.</p>"},{"location":"features/DevReadMe/#about-aca-py-command-line-parameters","title":"About ACA-Py Command Line Parameters","text":"<p>ACA-Py invocations are separated into two types - initially provisioning an agent (<code>provision</code>) and starting a new agent process (<code>start</code>). This separation enables not having to pass in some encryption-related parameters required for provisioning when starting an agent instance. This improves security in production deployments.</p> <p>When starting an agent instance, at least one inbound and one outbound transport MUST be specified.</p> <p>For example:</p> <pre><code>aca-py start    --inbound-transport http 0.0.0.0 8000 \\\n                --outbound-transport http\n</code></pre> <p>or</p> <pre><code>aca-py start    --inbound-transport http 0.0.0.0 8000 \\\n                --inbound-transport ws 0.0.0.0 8001 \\\n                --outbound-transport ws \\\n                --outbound-transport http\n</code></pre> <p>ACA-Py ships with both inbound and outbound transport drivers for <code>http</code> and <code>ws</code> (websockets). Additional transport drivers can be added as pluggable implementations. See the existing implementations in the transports module for getting started on adding a new transport.</p> <p>Most configuration parameters are provided to the agent at startup. Refer to the <code>Running</code> sections above for details on listing the available command line parameters.</p>"},{"location":"features/DevReadMe/#provisioning-secure-storage","title":"Provisioning Secure Storage","text":"<p>It is possible to provision a secure storage (sometimes called a wallet--but not the same as a mobile wallet app) before running an agent to avoid passing in the secure storage seed on every invocation of an agent (e.g. on every <code>aca-py start ...</code>).</p> <pre><code>aca-py provision --wallet-type askar --seed $SEED\n</code></pre> <p>For additional <code>provision</code> options, execute <code>aca-py provision --help</code>.</p> <p>Additional information about secure storage options and configuration settings can be found here.</p>"},{"location":"features/DevReadMe/#mediation","title":"Mediation","text":"<p>ACA-Py can also run in mediator mode - ACA-Py can be run as a mediator (it can mediate connections for other agents), or it can connect to an external mediator to mediate its own connections.  See the docs on mediation for more info.</p>"},{"location":"features/DevReadMe/#multi-tenancy","title":"Multi-tenancy","text":"<p>ACA-Py can also be started in multi-tenant mode. This allows the agent to serve multiple tenants, that each have their own wallet. See the docs on multi-tenancy for more info.</p>"},{"location":"features/DevReadMe/#json-ld-credentials","title":"JSON-LD Credentials","text":"<p>ACA-Py can issue W3C Verifiable Credentials using Linked Data Proofs. See the docs on JSON-LD Credentials for more info.</p>"},{"location":"features/DevReadMe/#developing","title":"Developing","text":""},{"location":"features/DevReadMe/#prerequisites","title":"Prerequisites","text":"<p>Docker must be installed to run software locally and to run the test suite.</p>"},{"location":"features/DevReadMe/#running-in-a-dev-container","title":"Running In A Dev Container","text":"<p>The dev container environment is a great way to deploy agents quickly with code changes and an interactive debug session. Detailed information can be found in the Docs On Devcontainers. It is specific for vscode, so if you prefer another code editor or IDE you will need to figure it out on your own, but it is highly recommended to give this a try.</p> <p>One thing to be aware of is, unlike the demo, none of the steps are automated. You will need to create public dids, connections and all the other steps yourself. Using the demo and studying the flow and then copying them with your dev container debug session is a great way to learn how everything works.</p>"},{"location":"features/DevReadMe/#running-locally","title":"Running Locally","text":"<p>Another way to develop locally is by using the provided Docker scripts to run the ACA-Py software.</p> <pre><code>./scripts/run_docker start &lt;args&gt;\n</code></pre> <p>For example:</p> <pre><code>./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG\n</code></pre> <p>To enable the ptvsd Python debugger for Visual Studio/VSCode use the <code>--debug</code> command line parameter.</p> <p>Any ports you will be using from the docker container should be published using the <code>PORTS</code> environment variable. For example:</p> <pre><code>PORTS=\"5000:5000 8000:8000 10000:10000\" ./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG\n</code></pre> <p>Refer to the previous section for instructions on how to run ACA-Py.</p>"},{"location":"features/DevReadMe/#logging","title":"Logging","text":"<p>You can find more details about logging and log levels here.</p>"},{"location":"features/DevReadMe/#running-tests","title":"Running Tests","text":"<p>To run the ACA-Py test suite, use the following script:</p> <pre><code>./scripts/run_tests\n</code></pre> <p>To run the ACA-Py test suite with ptvsd debugger enabled:</p> <pre><code>./scripts/run_tests --debug\n</code></pre> <p>To run specific tests pass parameters as defined by pytest:</p> <pre><code>./scripts/run_tests aries_cloudagent/protocols/connections\n</code></pre> <p>To run the tests including Indy SDK and related dependencies, run the script:</p> <pre><code>./scripts/run_tests_indy\n</code></pre>"},{"location":"features/DevReadMe/#running-aries-agent-test-harness-tests","title":"Running Aries Agent Test Harness Tests","text":"<p>You can run a full suite of integration tests using the Aries Agent Test Harness (AATH).</p> <p>Check out and run AATH tests as follows (this tests the aca-py <code>main</code> branch):</p> <pre><code>git clone https://github.com/hyperledger/aries-agent-test-harness.git\ncd aries-agent-test-harness\n./manage build -a acapy-main\n./manage run -d acapy-main -t @AcceptanceTest -t ~@wip\n</code></pre> <p>The <code>manage</code> script is described in detail here, including how to modify the AATH code to run the tests against your aca-py repo/branch.</p>"},{"location":"features/DevReadMe/#development-workflow","title":"Development Workflow","text":"<p>We use Ruff to enforce a coding style guide.</p> <p>We use Black to automatically format code.</p> <p>Please write tests for the work that you submit.</p> <p>Tests should reside in a directory named <code>tests</code> alongside the code under test. Generally, there is one test file for each file module under test. Test files must have a name starting with <code>test_</code> to be automatically picked up the test runner.</p> <p>There are some good examples of various test scenarios for you to work from including mocking external imports and working with async code so take a look around!</p> <p>The test suite also displays the current code coverage after each run so you can see how much of your work is covered by tests. Use your best judgement for how much coverage is sufficient.</p> <p>Please also refer to the contributing guidelines and code of conduct.</p>"},{"location":"features/DevReadMe/#publishing-releases","title":"Publishing Releases","text":"<p>The publishing document provides information on tagging a release and publishing the release artifacts to PyPi.</p>"},{"location":"features/DevReadMe/#dynamic-injection-of-services","title":"Dynamic Injection of Services","text":"<p>The Agent employs a dynamic injection system whereby providers of base classes are registered with the <code>RequestContext</code> instance, currently within <code>conductor.py</code>. Message handlers and services request an instance of the selected implementation using <code>context.inject(BaseClass)</code>; for instance the wallet instance may be injected using <code>wallet = context.inject(BaseWallet)</code>. The <code>inject</code> method normally throws an exception if no implementation of the base class is provided, but can be called with <code>required=False</code> for optional dependencies (in which case a value of <code>None</code> may be returned).</p> <p>Providers are registered with either <code>context.injector.bind_instance(BaseClass, instance)</code> for previously-constructed (singleton) object instances, or <code>context.injector.bind_provider(BaseClass, provider)</code> for dynamic providers. In some cases it may be desirable to write a custom provider which switches implementations based on configuration settings, such as the wallet provider.</p> <p>The <code>BaseProvider</code> classes in the <code>config.provider</code> module include <code>ClassProvider</code>, which can perform dynamic module inclusion when given the combined module and class name as a string (for instance <code>aries_cloudagent.wallet.indy.IndyWallet</code>). <code>ClassProvider</code> accepts additional positional and keyword arguments to be passed into the class constructor. Any of these arguments may be an instance of <code>ClassProvider.Inject(BaseClass)</code>, allowing dynamic injection of dependencies when the class instance is instantiated.</p>"},{"location":"features/Endorser/","title":"Transaction Endorser Support","text":"<p>ACA-Py supports an Endorser Protocol, that allows an un-privileged agent (an \"Author\") to request another agent (the \"Endorser\") to sign their transactions so they can write these transactions to the ledger.  This is required on Indy ledgers, where new agents will typically be granted only \"Author\" privileges.</p> <p>Transaction Endorsement is built into the protocols for Schema, Credential Definition and Revocation, and endorsements can be explicitly requested, or ACA-Py can be configured to automate the endorsement workflow.</p>"},{"location":"features/Endorser/#setting-up-connections-between-authors-and-endorsers","title":"Setting up Connections between Authors and Endorsers","text":"<p>Since endorsement involves message exchange between two agents, these agents must establish and configure a connection before any endorsements can be provided or requested.</p> <p>Once the connection is established and <code>active</code>, the \"role\" (either Author or Endorser) is attached to the connection using the <code>/transactions/{conn_id}/set-endorser-role</code> endpoint.  For Authors, they must additionally configure the DID of the Endorser as this is required when the Author signs the transaction (prior to sending to the Endorser for endorsement) - this is done using the <code>/transactions/{conn_id}/set-endorser-info</code> endpoint.</p>"},{"location":"features/Endorser/#requesting-transaction-endorsement","title":"Requesting Transaction Endorsement","text":"<p>Transaction Endorsement is built into the protocols for Schema, Credential Definition and Revocation.  When executing one of the endpoints that will trigger a ledger write, an endorsement protocol can be explicitly requested by specifying the <code>connection_id</code> (of the Endorser connection) and <code>create_transaction_for_endorser</code>.</p> <p>(Note that endorsement requests can be automated, see the section on \"Configuring ACA-Py\" below.)</p> <p>If transaction endorsement is requested, then ACA-Py will create a transaction record (this will be returned by the endpoint, rather than the Schema, Cred Def, etc) and the following endpoints must be invoked:</p> Protocol Step Author Endorser Request Endorsement <code>/transactions/create-request</code> Endorse Transaction <code>/transactions/{tran_id}/endorse</code> Write Transaction <code>/transactions/{tran_id}/write</code> <p>Additional endpoints allow the Endorser to reject the endorsement request, or for the Author to re-submit or cancel a request.</p> <p>Web hooks will be triggered to notify each ACA-Py agent of any transaction request, endorsements, etc to allow the controller to react to the event, or the process can be automated via command-line parameters (see below).</p>"},{"location":"features/Endorser/#configuring-aca-py-for-auto-or-manual-endorsement","title":"Configuring ACA-Py for Auto or Manual Endorsement","text":"<p>The following start-up parameters are supported by ACA-Py:</p> <pre><code>Endorsement:\n  --endorser-protocol-role &lt;endorser-role&gt;\n                        Specify the role ('author' or 'endorser') which this agent will participate. Authors will request transaction endorsement from an Endorser. Endorsers will endorse transactions from\n                        Authors, and may write their own transactions to the ledger. If no role (or 'none') is specified then the endorsement protocol will not be used and this agent will write transactions to\n                        the ledger directly. [env var: ACAPY_ENDORSER_ROLE]\n  --endorser-public-did &lt;endorser-public-did&gt;\n                        For transaction Authors, specify the public DID of the Endorser agent who will be endorsing transactions. Note this requires that the connection be made using the Endorser's public\n                        DID. [env var: ACAPY_ENDORSER_PUBLIC_DID]\n  --endorser-alias &lt;endorser-alias&gt;\n                        For transaction Authors, specify the alias of the Endorser connection that will be used to endorse transactions. [env var: ACAPY_ENDORSER_ALIAS]\n  --auto-request-endorsement\n                        For Authors, specify whether to automatically request endorsement for all transactions. (If not specified, the controller must invoke the request endorse operation for each\n                        transaction.) [env var: ACAPY_AUTO_REQUEST_ENDORSEMENT]\n  --auto-endorse-transactions\n                        For Endorsers, specify whether to automatically endorse any received endorsement requests. (If not specified, the controller must invoke the endorsement operation for each transaction.)\n                        [env var: ACAPY_AUTO_ENDORSE_TRANSACTIONS]\n  --auto-write-transactions\n                        For Authors, specify whether to automatically write any endorsed transactions. (If not specified, the controller must invoke the write transaction operation for each transaction.) [env\n                        var: ACAPY_AUTO_WRITE_TRANSACTIONS]\n  --auto-create-revocation-transactions\n                        For Authors, specify whether to automatically create transactions for a cred def's revocation registry. (If not specified, the controller must invoke the endpoints required to create\n                        the revocation registry and assign to the cred def.) [env var: ACAPY_CREATE_REVOCATION_TRANSACTIONS]\n  --auto-promote-author-did\n                        For Authors, specify whether to automatically promote a DID to the wallet public DID after writing to the ledger. [env var: ACAPY_AUTO_PROMOTE_AUTHOR_DID]\n</code></pre>"},{"location":"features/Endorser/#how-aca-py-handles-endorsements","title":"How Aca-py Handles Endorsements","text":"<p>Internally, the Endorsement functionality is implemented as a protocol, and is implemented consistently with other protocols:</p> <ul> <li>a routes.py file exposes the admin endpoints</li> <li>handler files implement responses to any received Endorse protocol messages</li> <li>a manager.py file implements common functionality that is called from both the routes.py and handler classes (as well as from other classes that need to interact with Endorser functionality)</li> </ul> <p>The Endorser makes use of the Event Bus (links to the PR which links to a hackmd doc) to notify other protocols of any Endorser events of interest.  For example, after a Credential Definition endorsement is received, the TransactionManager writes the endorsed transaction to the ledger and uses the Event Bus to notify the Credential Definition manager that it can do any required post-processing (such as writing the cred def record to the wallet, initiating the revocation registry, etc.).</p> <p>The overall architecture can be illustrated as:</p> <p></p>"},{"location":"features/Endorser/#create-credential-definition-and-revocation-registry","title":"Create Credential Definition and Revocation Registry","text":"<p>An example of an Endorser flow is as follows, showing how a credential definition endorsement is received and processed, and optionally kicks off the revocation registry process:</p> <p></p> <p>You can see that there is a standard endorser flow happening each time there is a ledger write (illustrated in the \"Endorser\" process).</p> <p>At the end of each endorse sequence, the TransactionManager sends a notification via the EventBus so that any dependant processing can continue.  Each Router is responsible for listening and responding to these notifications if necessary.</p> <p>For example:</p> <ul> <li>Once the credential definition is created, a revocation registry must be created (for revocable cred defs)</li> <li>Once the revocation registry is created, a revocation entry must be created</li> <li>Potentially, the cred def status could be updated once the revocation entry is completed</li> </ul> <p>Using the EventBus decouples the event sequence.  Any functions triggered by an event notification are typically also available directly via Admin endpoints.</p>"},{"location":"features/Endorser/#create-did-and-promote-to-public","title":"Create DID and Promote to Public","text":"<p>... and an example of creating a DID and promoting it to public (and creating an ATTRIB for the endpoint:</p> <p></p> <p>You can see the same endorsement processes in this sequence.</p> <p>Once the DID is written, the DID can (optionally) be promoted to the public DID, which will also invoke an ATTRIB transaction to write the endpoint.</p>"},{"location":"features/JsonLdCredentials/","title":"JSON-LD Credentials in ACA-Py","text":"<p>By design Hyperledger Aries is credential format agnostic. This means you can use it for any credential format, as long as an RFC is defined for the specific credential format. ACA-Py currently supports two types of credentials, Indy and JSON-LD credentials. This document describes how to use the latter by making use of W3C Verifiable Credentials using Linked Data Proofs.</p>"},{"location":"features/JsonLdCredentials/#table-of-contents","title":"Table of Contents","text":"<ul> <li>General Concept</li> <li>BBS+</li> <li>Preparing to Issue a Credential</li> <li>JSON-LD Context<ul> <li>Writing JSON-LD Contexts</li> </ul> </li> <li>Signature Suite</li> <li>Did Method<ul> <li><code>did:sov</code></li> <li><code>did:key</code></li> </ul> </li> <li>Issuing Credentials</li> <li>Retrieving Issued Credentials</li> <li>Present Proof</li> <li>VC-API</li> </ul>"},{"location":"features/JsonLdCredentials/#general-concept","title":"General Concept","text":"<p>The rest of this guide assumes some basic understanding of W3C Verifiable Credentials, JSON-LD and Linked Data Proofs. If you're not familiar with some of these concepts, the following resources can help you get started:</p> <ul> <li>Verifiable Credentials Data Model</li> <li>JSON-LD Articles and Presentations</li> <li>Linked Data Proofs</li> </ul>"},{"location":"features/JsonLdCredentials/#bbs","title":"BBS+","text":"<p>BBS+ credentials offer a lot of privacy preserving features over non-ZKP credentials. Therefore we recommend to always use BBS+ credentials over non-ZKP credentials. To get started with BBS+ credentials it is recommended to at least read RFC 0646: W3C Credential Exchange using BBS+ Signatures for a general overview.</p> <p>Some other resources that can help you get started with BBS+ credentials:</p> <ul> <li>BBS+ Signatures 2020</li> <li>Video: BBS+ Credential Exchange in Hyperledger Aries</li> </ul>"},{"location":"features/JsonLdCredentials/#preparing-to-issue-a-credential","title":"Preparing to Issue a Credential","text":"<p>Contrary to Indy credentials, JSON-LD credentials do not need a schema or credential definition to issue credentials. Everything required to issue the credential is embedded into the credential itself using Linked Data Contexts.</p>"},{"location":"features/JsonLdCredentials/#json-ld-context","title":"JSON-LD Context","text":"<p>It is required that every property key in the document can be mapped to an IRI. This means the property key must either be an IRI by default, or have the shorthand property mapped in the <code>@context</code> of the document. If you have properties that are not mapped to IRIs, the Issue Credential API will throw the following error:</p> <p><code>&lt;x&gt; attributes dropped. Provide definitions in context to correct. [&lt;missing-properties&gt;]</code></p> <p>For credentials the <code>https://www.w3.org/2018/credentials/v1</code> context MUST always be the first context. In addition, when issuing BBS+ credentials the <code>https://w3id.org/security/bbs/v1</code> URL MUST be present in the context. For convenience this URL will be automatically added to the <code>@context</code> of the credential if not present.</p> <pre><code>{\n  \"@context\": [\n    \"https://www.w3.org/2018/credentials/v1\",\n    \"https://other-contexts.com\"\n  ]\n}\n</code></pre>"},{"location":"features/JsonLdCredentials/#writing-json-ld-contexts","title":"Writing JSON-LD Contexts","text":"<p>Writing JSON-LD contexts can be a daunting task and is out of scope of this guide. Generally you should try to make use of already existing vocabularies. Some examples are the vocabularies defined in the W3C Credentials Community Group:</p> <ul> <li>Vaccination Certificate Vocabulary</li> <li>Citizenship Vocabulary</li> <li>Traceability Vocabulary</li> </ul> <p>Verifiable credentials are not around that long, so there aren't that many vocabularies ready to use. If you can't use one of the existing vocabularies it is still beneficial to lean on already defined lower level contexts. http://schema.org has a large registry of definitions that can be used to build new contexts. The example vocabularies linked above all make use of types from http://schema.org.</p> <p>For the remainder of this guide, we will be using the example <code>UniversityDegreeCredential</code> type and <code>https://www.w3.org/2018/credentials/examples/v1</code> context from the Verifiable Credential Data Model. You should not use this for production use cases.</p>"},{"location":"features/JsonLdCredentials/#signature-suite","title":"Signature Suite","text":"<p>Before issuing a credential you must determine a signature suite to use. ACA-Py currently supports two signature suites for issuing credentials:</p> <ul> <li><code>Ed25519Signature2018</code> - Very well supported. No zero knowledge proofs or selective disclosure.</li> <li><code>BbsBlsSignature2020</code> - Newer, but supports zero knowledge proofs and selective disclosure.</li> </ul> <p>Generally you should always use <code>BbsBlsSignature2020</code> as it allows the holder to derive a new credential during the proving, meaning it doesn't have to disclose all fields and doesn't have to reveal the signature.</p>"},{"location":"features/JsonLdCredentials/#did-method","title":"Did Method","text":"<p>Besides the JSON-LD context, we need a did to use for issuing the credential. ACA-Py currently supports two did methods for issuing credentials:</p> <ul> <li><code>did:sov</code> - Can only be used for <code>Ed25519Signature2018</code> signature suite.</li> <li><code>did:key</code> - Can be used for both <code>Ed25519Signature2018</code> and <code>BbsBlsSignature2020</code> signature suites.</li> </ul>"},{"location":"features/JsonLdCredentials/#didsov","title":"<code>did:sov</code>","text":"<p>When using <code>did:sov</code> you need to make sure to use a public did so other agents can resolve the did. It is also important the other agent is using the same indy ledger for resolving the did. You can get the public did using the <code>/wallet/did/public</code> endpoint. For backwards compatibility the did is returned without <code>did:sov</code> prefix. When using the did for issuance make sure this prepend this to the did. (so <code>DViYrCMPWfuLiY7LLs8giB</code> becomes <code>did:sov:DViYrCMPWfuLiY7LLs8giB</code>)</p>"},{"location":"features/JsonLdCredentials/#didkey","title":"<code>did:key</code>","text":"<p>A <code>did:key</code> did is not anchored to a ledger, but embeds the key directly in the identifier part of the did. See the did:key Method Specification for more information.</p> <p>You can create a <code>did:key</code> using the <code>/wallet/did/create</code> endpoint with the following body. Use <code>ed25519</code> for <code>Ed25519Signature2018</code>, <code>bls12381g2</code> for <code>BbsBlsSignature2020</code>.</p> <pre><code>{\n  \"method\": \"key\",\n  \"options\": {\n    \"key_type\": \"bls12381g2\" // or ed25519\n  }\n}\n</code></pre> <p>The above call will return a did that looks something like this: <code>did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj</code></p>"},{"location":"features/JsonLdCredentials/#issuing-credentials","title":"Issuing Credentials","text":"<p>Issuing JSON-LD credentials is only possible with the issue credential v2 protocol (<code>/issue-credential-2.0</code>)</p> <p>The format used for exchanging JSON-LD credentials is defined in RFC 0593: JSON-LD Credential Attachment format. The API in ACA-Py exactly matches the formats as described in this RFC, with the most important (from the ACA-Py API perspective) being <code>aries/ld-proof-vc-detail@v1.0</code>. Read the RFC to see the exact properties required to construct a valid Linked Data Proof VC Detail.</p> <p>All endpoints in API use the <code>aries/ld-proof-vc-detail@v1.0</code>. We'll use the <code>/issue-credential-2.0/send</code> as an example, but it works the same for the other endpoints. In contrary to issuing indy credentials, JSON-LD credentials do not require a credential preview. All properties should be directly embedded in the credentials.</p> <p>The detail should be included under the <code>filter.ld_proof</code> property. To issue a credential call the <code>/issue-credential-2.0/send</code> endpoint, with the example body below and the <code>connection_id</code> and <code>issuer</code> keys replaced. The value of <code>issuer</code> should be the did that you created in the Did Method paragraph above.</p> <p>If you don't have <code>auto-respond-credential-offer</code> and <code>auto-store-credential</code> enabled in the ACA-Py config, you will need to call <code>/issue-credential-2.0/records/{cred_ex_id}/send-request</code> and <code>/issue-credential-2.0/records/{cred_ex_id}/store</code> to finalize the credential issuance.</p> See the example body <pre><code>{\n  \"connection_id\": \"ddc23de9-359f-465c-b66e-f7c5a0cc9a57\",\n  \"filter\": {\n    \"ld_proof\": {\n      \"credential\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"UniversityDegreeCredential\"],\n        \"issuer\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        }\n      },\n      \"options\": {\n        \"proofType\": \"BbsBlsSignature2020\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"features/JsonLdCredentials/#retrieving-issued-credentials","title":"Retrieving Issued Credentials","text":"<p>After issuing the credential, the credentials should be stored inside the wallet. Because the structure of JSON-LD credentials is so different from indy credentials a new endpoint is added to retrieve W3C credentials.</p> <p>Call the <code>/credentials/w3c</code> endpoint to retrieve all JSON-LD credentials in your wallet. See the detail below for an example response based on the issued credential from the Issuing Credentials paragraph above.</p> See the example response <pre><code>{\n  \"results\": [\n    {\n      \"contexts\": [\n        \"https://www.w3.org/2018/credentials/examples/v1\",\n        \"https://www.w3.org/2018/credentials/v1\",\n        \"https://w3id.org/security/bbs/v1\"\n      ],\n      \"types\": [\"UniversityDegreeCredential\", \"VerifiableCredential\"],\n      \"schema_ids\": [],\n      \"issuer_id\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n      \"subject_ids\": [],\n      \"proof_types\": [\"BbsBlsSignature2020\"],\n      \"cred_value\": {\n        \"@context\": [\n          \"https://www.w3.org/2018/credentials/v1\",\n          \"https://www.w3.org/2018/credentials/examples/v1\",\n          \"https://w3id.org/security/bbs/v1\"\n        ],\n        \"type\": [\"VerifiableCredential\", \"UniversityDegreeCredential\"],\n        \"issuer\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n        \"issuanceDate\": \"2020-01-01T12:00:00Z\",\n        \"credentialSubject\": {\n          \"degree\": {\n            \"type\": \"BachelorDegree\",\n            \"name\": \"Bachelor of Science and Arts\"\n          },\n          \"college\": \"Faber College\"\n        },\n        \"proof\": {\n          \"type\": \"BbsBlsSignature2020\",\n          \"proofPurpose\": \"assertionMethod\",\n          \"verificationMethod\": \"did:key:zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj#zUC7FsmhhifDTuYXdwYES2UpCpWwYieJRapC6oEWqyt5KfJ3ztfLzYnbWjuXQ5drYaKaho3FjxrfDB81gtAJKjbM4yAmBuNoj3YKDXqW151KkkYarpEoEVWMMcN5zPfjCrQ8Saj\",\n          \"created\": \"2021-05-03T12:31:28.561945\",\n          \"proofValue\": \"iUFtRGdLLCWxKx8VD3oiFBoRMUFKhSitTzMsfImXm6OF0d8il+Z40aLz8S7m8EcXPQhRjcWWL9jkfcf1SDifD4CvxVg69NvB7hZyIIz9hwAyi3LmTm0ez4NDRCKyieBuzqKbfM2eACWn/ilhOJBm6w==\"\n        }\n      },\n      \"cred_tags\": {},\n      \"record_id\": \"541ddbce5760497d98e68917be8c05bd\"\n    }\n  ]\n}\n</code></pre>"},{"location":"features/JsonLdCredentials/#present-proof","title":"Present Proof","text":"<p>\u26a0\ufe0f TODO: https://github.com/hyperledger/aries-cloudagent-python/pull/1125</p>"},{"location":"features/JsonLdCredentials/#vc-api","title":"VC-API","text":"<p>In order to support these functions outside of the respective DIDComm protocols, a set of endpoints conforming to the vc-api specification are available. These endpoints should be used by a controller when building an identity platform.</p> <p>These endpoints include:</p> <ul> <li><code>GET /vc/credentials</code> -&gt; returns a list of all stored json-ld credentials</li> <li><code>GET /vc/credentials/{id}</code> -&gt; returns a json-ld credential based on it's ID</li> <li><code>POST /vc/credentials/issue</code> -&gt; signs a credential</li> <li><code>POST /vc/credentials/verify</code> -&gt; verifies a credential</li> <li><code>POST /vc/credentials/store</code> -&gt; stores an issued credential</li> <li><code>POST /vc/presentations/prove</code> -&gt; proves a presentation</li> <li><code>POST /vc/presentations/verify</code> -&gt; verifies a presentation</li> </ul> <p>To learn more about using these endpoints, please refer to the available postman collection.</p>"},{"location":"features/Mediation/","title":"Mediation docs","text":""},{"location":"features/Mediation/#concepts","title":"Concepts","text":"<ul> <li>DIDComm Message Forwarding - Sending an encrypted message to its recipient by first sending it to a third party responsible for forwarding the message on. Message contents are encrypted once for the recipient then wrapped in a forward message encrypted to the third party.</li> <li>Mediator - An agent that forwards messages to a client over a DIDComm connection.</li> <li>Mediated Agent or Mediation client - The agent(s) to which a mediator is willing to forward messages.</li> <li>Mediation Request - A message from a client to a mediator requesting mediation or forwarding.</li> <li>Keylist - The list of public keys used by the mediator to lookup to which connection a forward message should be sent. Each mediated agent is responsible for maintaining the keylist with the mediator.</li> <li>Keylist Update - A message from a client to a mediator informing the mediator of changes to the keylist.</li> <li>Default Mediator - A mediator to be used with every newly created DIDComm connection.</li> <li>Mediation Connection - Connection between the mediator and the mediated agent or client. Agents can use as many mediators as the identity owner sees fit. Requests for mediation are handled on a per connection basis.</li> <li>See Aries RFC 0211: Coordinate Mediation Protocol for additional details on message attributes and more.</li> </ul>"},{"location":"features/Mediation/#command-line-arguments","title":"Command Line Arguments","text":"<ul> <li><code>--open-mediation</code> - Instructs mediators to automatically grant all incoming mediation requests.</li> <li><code>--mediator-invitation</code> - Receive invitation, send mediation request and set as default mediator.</li> <li><code>--mediator-connections-invite</code> - Connect to mediator through a connection invitation. If not specified, connect using an OOB invitation.</li> <li><code>--default-mediator-id</code> - Set pre-existing mediator as default mediator.</li> <li><code>--clear-default-mediator</code> - Clear the stored default mediator.</li> </ul> <p>The minimum set of arguments required to enable mediation are:</p> <pre><code>aca-py start ... \\\n    --open-mediation\n</code></pre> <p>To automate the mediation process on startup, additionally specify the following argument on the mediated agent (not the mediator):</p> <pre><code>aca-py start ... \\\n    --mediator-invitation \"&lt;a multi-use invitation url from the mediator&gt;\"\n</code></pre> <p>If a default mediator has already been established, then the <code>--default-mediator-id</code> argument can be used instead of the <code>--mediator-invitation</code>.</p>"},{"location":"features/Mediation/#didcomm-messages","title":"DIDComm Messages","text":"<p>See Aries RFC 0211: Coordinate Mediation Protocol.</p>"},{"location":"features/Mediation/#admin-api","title":"Admin API","text":"<ul> <li><code>GET mediation/requests</code></li> <li>Return a list of all mediation records. Filter by <code>conn_id</code>, <code>state</code>, <code>mediator_terms</code> and <code>recipient_terms</code>.</li> <li><code>GET mediation/requests/{mediation_id}</code></li> <li>Retrieve a mediation record by id.</li> <li><code>DELETE mediation/requests/{mediation_id}</code></li> <li>Delete mediation record by id.</li> <li><code>POST mediation/requests/{mediation_id}/grant</code></li> <li>As a mediator, grant a stored mediation request and send <code>granted</code> message to client.</li> <li><code>POST mediation/requests/{mediation_id}/deny</code></li> <li>As a mediator, deny a stored mediation request and send <code>denied</code> message to client.</li> <li><code>POST mediation/request/{conn_id}</code></li> <li>Send a mediation request to connection identified by the given connection ID.</li> <li><code>GET mediation/keylists</code></li> <li>Returns key list associated with a connection. Filter on <code>client</code> for keys mediated by other agents and <code>server</code> for keys mediated by this agent.</li> <li><code>POST mediation/keylists/{mediation_id}/send-keylist-update</code></li> <li>Send keylist update message to mediator identified by the given mediation ID. Updates contained in body of request.</li> <li><code>POST mediation/keylists/{mediation_id}/send-keylist-query</code></li> <li>Send keylist query message to mediator identified by the given mediation ID.</li> <li><code>GET mediation/default-mediator</code> (PR pending)</li> <li>Retrieve the currently set default mediator.</li> <li><code>PUT mediation/{mediation_id}/default-mediator</code> (PR pending)</li> <li>Set the mediator identified by the given mediation ID as the default mediator.</li> <li><code>DELETE mediation/default-mediator</code> (PR pending)</li> <li>Clear the currently set default mediator (mediation status is maintained and remains functional, just not used as the default).</li> </ul>"},{"location":"features/Mediation/#mediator-message-flow-overview","title":"Mediator Message Flow Overview","text":""},{"location":"features/Mediation/#using-a-mediator","title":"Using a Mediator","text":"<p>After establishing a connection with a mediator also having mediation granted, you can use that mediator id for future did_comm connections.  When creating, receiving or accepting an invitation intended to be Mediated, you provide <code>mediation_id</code> with the desired mediator id. if using a single mediator for all future connections, You can set a default mediation id. If no mediation_id is provided the default mediation id will be used instead.</p>"},{"location":"features/Multicredentials/","title":"Multi-Credentials","text":"<p>It is a known fact that multiple AnonCreds can be combined to present a presentation proof with an \"and\" logical operator: For instance, a verifier can ask for the \"name\" claim from an eID and the \"address\" claim from a bank statement to have a single proof that is either valid or invalid. With the Present Proof Protocol v2, it is possible to have \"and\" and \"or\" logical operators for AnonCreds and/or W3C Verifiable Credentials.</p> <p>With the Present Proof Protocol v2, verifiers can ask for a combination of credentials as proof. For instance, a Verifier can ask a claim from an AnonCreds and a verifiable presentation from a W3C Verifiable Credential, which would open the possibilities of Aries Cloud Agent Python being used for rather complex presentation proof requests that wouldn't be possible without the support of AnonCreds or W3C Verifiable Credentials.</p> <p>Moreover, it is possible to make similar presentation proof requests using the or logical operator. For instance, a verifier can ask for either an eID in AnonCreds format or an eID in W3C Verifiable Credential format. This has the potential to solve the interoperability problem of different credential formats and ecosystems from a user point of view by shifting the requirement of holding/accepting different credential formats from identity holders to verifiers. Here again, using Aries Cloud Agent Python as the underlying verifier agent can tackle such complex presentation proof requests since the agent is capable of verifying both type of credential formats and proof types.</p> <p>In the future, it would be even possible to put mDoc as an attachment with an and or or logical operation, along with AnonCreds and/or W3C Verifiable Credentials. For this to happen, Aca-Py either needs the capabilities to validate mDocs internally or to connect third-party endpoints to validate and get a response.</p>"},{"location":"features/Multiledger/","title":"Multi-ledger in ACA-Py","text":"<p>Ability to use multiple Indy ledgers (both IndySdk and IndyVdr) for resolving a <code>DID</code> by the ACA-Py agent. For read requests, checking of multiple ledgers in parallel is done dynamically according to logic detailed in Read Requests Ledger Selection. For write requests, dynamic allocation of <code>write_ledger</code> is supported. Configurable write ledgers can be assigned using <code>is_write</code> in the configuration or using any of the <code>--genesis-url</code>, <code>--genesis-file</code>, and <code>--genesis-transactions</code> startup (ACA-Py) arguments. If no write ledger is assigned then a <code>ConfigError</code> is raised.</p> <p>More background information including problem statement, design (algorithm) and more can be found here.</p>"},{"location":"features/Multiledger/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Usage</li> <li>Example config file</li> <li>Config properties</li> <li>Multi-ledger Admin API</li> <li>Ledger Selection</li> <li>Read Requests<ul> <li>For checking ledger in parallel</li> </ul> </li> <li>Write Requests</li> <li>A Special Warning for TAA Acceptance</li> <li>Impact on other ACA-Py function</li> <li>Known Issues</li> </ul>"},{"location":"features/Multiledger/#usage","title":"Usage","text":"<p>Multi-ledger is disabled by default. You can enable support for multiple ledgers using the <code>--genesis-transactions-list</code> startup parameter. This parameter accepts a string which is the path to the <code>YAML</code> configuration file. For example:</p> <p><code>--genesis-transactions-list ./aries_cloudagent/config/multi_ledger_config.yml</code></p> <p>If <code>--genesis-transactions-list</code> is specified, then <code>--genesis-url, --genesis-file, --genesis-transactions</code> should not be specified.</p>"},{"location":"features/Multiledger/#example-config-file","title":"Example config file","text":"<pre><code>- id: localVON\n  is_production: false\n  genesis_url: 'http://host.docker.internal:9000/genesis'\n- id: bcovrinTest\n  is_production: true\n  is_write: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n</code></pre> <pre><code>- id: localVON\n  is_production: false\n  genesis_url: 'http://host.docker.internal:9000/genesis'\n- id: bcovrinTest\n  is_production: true\n  is_write: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n  endorser_did: '9QPa6tHvBHttLg6U4xvviv'\n  endorser_alias: 'endorser_test'\n- id: greenlightDev\n  is_production: true\n  is_write: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n</code></pre> <p>Note: <code>is_write</code> property means that the ledger is write configurable. With reference to the above config example, both <code>bcovrinTest</code> and (the no longer available -- in the above its pointing to BCovrin Test as well) <code>greenlightDev</code> ledgers are write configurable. By default, on startup <code>bcovrinTest</code> will be the write ledger as it is the topmost write configurable production ledger, more details regarding the selection rule. Using <code>PUT /ledger/{ledger_id}/set-write-ledger</code> endpoint, either <code>greenlightDev</code> and <code>bcovrinTest</code> can be set as the write ledger.</p> <p>Note 2: The <code>greenlightDev</code> ledger is no longer available, so both ledger entries in the example above and below intentionally point to the same ledger URL.</p> <pre><code>- id: localVON\n  is_production: false\n  is_write: true\n  genesis_url: 'http://host.docker.internal:9000/genesis'\n- id: bcovrinTest\n  is_production: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n- id: greenlightDev\n  is_production: true\n  genesis_url: 'http://test.bcovrin.vonx.io/genesis'\n</code></pre> <p>Note: For instance with regards to example config above, <code>localVON</code> will be the write ledger, as there are no production ledgers which are configurable it will choose the topmost write configurable non production ledger.</p>"},{"location":"features/Multiledger/#config-properties","title":"Config properties","text":"<p>For each ledger, the required properties are as following:</p> <ul> <li><code>id</code>*: The id (or name) of the ledger, can also be used as the pool name if none provided</li> <li><code>is_production</code>*: Whether the ledger is a production ledger. This is used by the pool selector algorithm to know which ledger to use for certain interactions (i.e. prefer production ledgers over non-production ledgers)</li> </ul> <p>For connecting to ledger, one of the following needs to be specified:</p> <ul> <li><code>genesis_file</code>: The path to the genesis file to use for connecting to an Indy ledger.</li> <li><code>genesis_transactions</code>: String of genesis transactions to use for connecting to an Indy ledger.</li> <li><code>genesis_url</code>: The url from which to download the genesis transactions to use for connecting to an Indy ledger.</li> </ul> <p>Optional properties:</p> <ul> <li><code>pool_name</code>: name of the indy pool to be opened</li> <li><code>keepalive</code>: how many seconds to keep the ledger open</li> <li><code>socks_proxy</code></li> <li><code>is_write</code>: Whether this ledger is writable. It requires at least one write ledger specified. Multiple write ledgers can be specified in config.</li> <li><code>endorser_did</code>: Endorser public DID registered on the ledger, needed for supporting Endorser protocol at multi-ledger level.</li> <li><code>endorser_alias</code>: Endorser alias for this ledger, needed for supporting Endorser protocol at multi-ledger level.</li> </ul> <p>Note: Both <code>endorser_did</code> and <code>endorser_alias</code> are part of the endorser info. Whenever a write ledger is selected using <code>PUT /ledger/{ledger_id}/set-write-ledger</code>, the endorser info associated with that ledger in the config updates the <code>endorser.endorser_public_did</code> and <code>endorser.endorser_alias</code> profile setting respectively.</p>"},{"location":"features/Multiledger/#multi-ledger-admin-api","title":"Multi-ledger Admin API","text":"<p>Multi-ledger related actions are grouped under the <code>ledger</code> topic in the SwaggerUI.</p> <ul> <li>GET <code>/ledger/config</code>: Returns the multiple ledger configuration currently in use</li> <li>GET <code>/ledger/get-write-ledger</code>: Returns the current active/set <code>write_ledger's</code> <code>ledger_id</code></li> <li>GET <code>/ledger/get-write-ledgers</code>: Returns list of available <code>write_ledger's</code> <code>ledger_id</code></li> <li>PUT <code>/ledger/{ledger_id}/set-write-ledger</code>: Set active <code>write_ledger's</code> <code>ledger_id</code></li> </ul>"},{"location":"features/Multiledger/#ledger-selection","title":"Ledger Selection","text":""},{"location":"features/Multiledger/#read-requests","title":"Read Requests","text":"<p>The following process is executed for these functions in ACA-Py:</p> <ol> <li><code>get_schema</code></li> <li><code>get_credential_definition</code></li> <li><code>get_revoc_reg_def</code></li> <li><code>get_revoc_reg_entry</code></li> <li><code>get_key_for_did</code></li> <li><code>get_all_endpoints_for_did</code></li> <li><code>get_endpoint_for_did</code></li> <li><code>get_nym_role</code></li> <li><code>get_revoc_reg_delta</code></li> </ol> <p>If multiple ledgers are configured then <code>IndyLedgerRequestsExecutor</code> service extracts <code>DID</code> from the record identifier and executes the check below, else it returns the <code>BaseLedger</code> instance.</p>"},{"location":"features/Multiledger/#for-checking-ledger-in-parallel","title":"For checking ledger in parallel","text":"<ul> <li><code>lookup_did_in_configured_ledgers</code> function</li> <li>If the calling function (above) is in items 1-4, then check the <code>DID</code> in <code>cache</code> for a corresponding applicable <code>ledger_id</code>. If found, return the ledger info, else continue.</li> <li>Otherwise, launch parallel <code>_get_ledger_by_did</code> tasks for each of the configured ledgers.</li> <li>As these tasks get finished, construct <code>applicable_prod_ledgers</code> and <code>applicable_non_prod_ledgers</code> dictionaries, each with <code>self_certified</code> and <code>non_self_certified</code> inner dict which are sorted by the original order or index.</li> <li>Order/preference for selection: <code>self_certified</code> &gt; <code>production</code> &gt; <code>non_production</code><ul> <li>Checks <code>production</code> ledger where the <code>DID</code> is <code>self_certified</code></li> <li>Checks <code>non_production</code> ledger where the <code>DID</code> is <code>self_certified</code></li> <li>Checks <code>production</code> ledger where the <code>DID</code> is not <code>self_certified</code></li> <li>Checks <code>non_production</code> ledger where the <code>DID</code> is not <code>self_certified</code></li> </ul> </li> <li>Return an applicable ledger if found, else raise an exception.</li> <li><code>_get_ledger_by_did</code> function</li> <li>Build and submit <code>GET_NYM</code></li> <li>Wait for a response for 10 seconds, if timed out return None</li> <li>Parse response</li> <li>Validate state proof</li> <li>Check if <code>DID</code> is self certified</li> <li>Returns ledger info to <code>lookup_did_in_configured_ledgers</code></li> </ul>"},{"location":"features/Multiledger/#write-requests","title":"Write Requests","text":"<p>On startup, the first configured applicable ledger is assigned as the <code>write_ledger</code> (<code>BaseLedger</code>), the selection is dependent on the order (top-down) and whether it is <code>production</code> or <code>non_production</code>. For instance, considering this example configuration, ledger <code>bcovrinTest</code> will be set as <code>write_ledger</code> as it is the topmost <code>production</code> ledger. If no <code>production</code> ledgers are included in configuration then the topmost <code>non_production</code> ledger is selected.</p>"},{"location":"features/Multiledger/#a-special-warning-for-taa-acceptance","title":"A Special Warning for TAA Acceptance","text":"<p>When you run in multi-ledger mode, ACA-Py will use the <code>pool-name</code> (or <code>id</code>) specified in the ledger configuration file for each ledger.</p> <p>(When running in single-ledger mode, ACA-Py uses <code>default</code> as the ledger name.)</p> <p>If you are running against a ledger in <code>write</code> mode, and the ledger requires you to accept a Transaction Author Agreement (TAA), ACA-Py stores the TAA acceptance status in the wallet in a non-secrets record, using the ledger's <code>pool_name</code> as a key.</p> <p>This means that if you are upgrading from single-ledger to multi-ledger mode, you will need to either:</p> <ul> <li>set the <code>id</code> for your writable ledger to <code>default</code> (in your <code>ledgers.yaml</code> file)</li> </ul> <p>or:</p> <ul> <li>re-accept the TAA once you restart your ACA-Py in multi-ledger mode</li> </ul> <p>Once you re-start ACA-Py, you can check the <code>GET /ledger/taa</code> endpoint to verify your TAA acceptance status.</p>"},{"location":"features/Multiledger/#impact-on-other-aca-py-function","title":"Impact on other ACA-Py function","text":"<p>There should be no impact/change in functionality to any ACA-Py protocols.</p> <p><code>IndySdkLedger</code> was refactored by replacing <code>wallet: IndySdkWallet</code> instance variable with <code>profile: Profile</code> and accordingly <code>.aries_cloudagent/indy/credex/verifier</code>, <code>.aries_cloudagent/indy/models/pres_preview</code>, <code>.aries_cloudagent/indy/sdk/profile.py</code>, <code>.aries_cloudagent/indy/sdk/verifier</code>, <code>./aries_cloudagent/indy/verifier</code> were also updated.</p> <p>Added <code>build_and_return_get_nym_request</code> and <code>submit_get_nym_request</code> helper functions to <code>IndySdkLedger</code> and <code>IndyVdrLedger</code>.</p> <p>Best practice/feedback emerging from <code>Askar session deadlock</code> issue and <code>endorser refactoring</code> PR was also addressed here by not leaving sessions open unnecessarily and changing <code>context.session</code> to <code>context.profile.session</code>, etc.</p> <p>These changes are made here:</p> <ul> <li><code>./aries_cloudagent/ledger/routes.py</code></li> <li><code>./aries_cloudagent/messaging/credential_definitions/routes.py</code></li> <li><code>./aries_cloudagent/messaging/schemas/routes.py</code></li> <li><code>./aries_cloudagent/protocols/actionmenu/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/actionmenu/v1_0/util.py</code></li> <li><code>./aries_cloudagent/protocols/basicmessage/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/coordinate_mediation/v1_0/handlers/keylist_handler.py</code></li> <li><code>./aries_cloudagent/protocols/coordinate_mediation/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/endorse_transaction/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/introduction/v0_1/handlers/invitation_handler.py</code></li> <li><code>./aries_cloudagent/protocols/introduction/v0_1/routes.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_issue_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_offer_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_proposal_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/handlers/credential_request_handler.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/issue_credential/v2_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/handlers/presentation_handler.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/handlers/presentation_proposal_handler.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/handlers/presentation_request_handler.py</code></li> <li><code>./aries_cloudagent/protocols/present_proof/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/protocols/trustping/v1_0/routes.py</code></li> <li><code>./aries_cloudagent/resolver/routes.py</code></li> <li><code>./aries_cloudagent/revocation/routes.py</code></li> </ul>"},{"location":"features/Multiledger/#known-issues","title":"Known Issues","text":"<ul> <li>When in multi-ledger mode and switching ledgers (e.g.: the agent is registered on Ledger A and has published its DID there, and now wants to \"move\" to Ledger B) there is an issue that will cause the registration to the new ledger to fail.</li> </ul>"},{"location":"features/Multitenancy/","title":"Multi-tenancy in ACA-Py","text":"<p>Most deployments of ACA-Py use a single wallet for all operations. This means all connections, credentials, keys, and everything else is stored in the same wallet and shared between all controllers of the agent. Multi-tenancy in ACA-Py allows multiple tenants to use the same ACA-Py instance with a different context. All tenants get their own encrypted wallet that only holds their own data.</p> <p>This allows ACA-Py to be used for a wider range of use cases. One use case could be a company that creates a wallet for each department. Each department has full control over the actions they perform while having a shared instance for easy maintenance. Another use case could be for a Issuer-Hosted Custodial Agent. Sometimes it is required to host the agent on behalf of someone else.</p>"},{"location":"features/Multitenancy/#table-of-contents","title":"Table of Contents","text":"<ul> <li>General Concept</li> <li>Base and Sub Wallets</li> <li>Usage</li> <li>Multi-tenant Admin API</li> <li>Managed vs Unmanaged Mode</li> <li>Managed Mode</li> <li>Unmanaged Mode</li> <li>Mode Usage</li> <li>Message Routing</li> <li>Relaying</li> <li>Mediation</li> <li>Webhooks</li> <li>Webhook URLs</li> <li>Identifying the wallet</li> <li>Authentication</li> <li>Getting a token<ul> <li>Method 1: Register new tenant</li> <li>Method 2: Get tenant token</li> </ul> </li> <li>JWT Secret</li> <li>SwaggerUI</li> <li>Tenant Management</li> <li>Update a tenant</li> <li>Remove a tenant</li> <li>Per tenant settings</li> </ul>"},{"location":"features/Multitenancy/#general-concept","title":"General Concept","text":"<p>When multi-tenancy is enabled in ACA-Py there is still a single agent running, however, some of the resources are now shared between the tenants of the agent. Each tenant has their own wallet, with their own DIDs, connections, and credentials. Transports and most of the settings are still shared between agents. Each wallet uses the same endpoint, so to the outside world, it is not obvious multiple tenants are using the same agent.</p>"},{"location":"features/Multitenancy/#base-and-sub-wallets","title":"Base and Sub Wallets","text":"<p>Multi-tenancy in ACA-Py makes a distinction between a base wallet and sub wallets.</p> <p>The wallets used by the different tenants are called sub wallets. A sub wallet is almost identical to a wallet when multi-tenancy is disabled. This means that you can do everything with it that a single-tenant ACA-Py instance can also do.</p> <p>The base wallet however, takes on a different role and has limited functionality. Its main function is to manage the sub wallets, which can be done using the Multi-tenant Admin API. It stores all settings and information about the different sub wallets and will route incoming messages to the corresponding sub wallets. See Message Routing for more details. All other features are disabled for the base wallet. This means it cannot issue credentials, present proof, or do any of the other actions sub wallets can do. This is to keep a clear hierarchical difference between base and sub wallets. For this reason, the base wallet should generally not be provisioned using the <code>--wallet-seed</code> argument as not only it is not necessary for sub wallet management operations, but it will also require this DID to be correctly registered on the ledger for the service to start-up correctly.</p> <p></p>"},{"location":"features/Multitenancy/#usage","title":"Usage","text":"<p>Multi-tenancy is disabled by default. You can enable support for multiple wallets using the <code>--multitenant</code> startup parameter. To also be able to manage wallets for the tenants, the multi-tenant admin API can be enabled using the <code>--multitenant-admin</code> startup parameter. See Multi-tenant Admin API below for more info on the admin API.</p> <p>The <code>--jwt-secret</code> startup parameter is required when multi-tenancy is enabled. This is used for JWT creation and verification. See Authentication below for more info.</p> <p>Example:</p> <pre><code># This enables multi-tenancy in ACA-Py\nmultitenant: true\n\n# This enables the admin API for multi-tenancy. More information below\nmultitenant-admin: true\n\n# This sets the secret used for JWT creation/verification for sub wallets\njwt-secret: Something very secret\n</code></pre>"},{"location":"features/Multitenancy/#multi-tenant-admin-api","title":"Multi-tenant Admin API","text":"<p>The multi-tenant admin API allows you to manage wallets in ACA-Py. Only the base wallet can manage wallets, so you can't for example create a wallet in the context of sub wallet (using the <code>Authorization</code> header as specified in Authentication).</p> <p>Multi-tenancy related actions are grouped under the <code>/multitenancy</code> path or the <code>multitenancy</code> topic in the SwaggerUI. As mentioned above, the multi-tenant admin API is disabled by default, event when multi-tenancy is enabled. This is to allow for more flexible agent configuration (e.g. horizontal scaling where only a single instance exposes the admin API). To enable the multi-tenant admin API, the <code>--multitenant-admin</code> startup parameter can be used.</p> <p>See the SwaggerUI for the exact API definition for multi-tenancy.</p>"},{"location":"features/Multitenancy/#managed-vs-unmanaged-mode","title":"Managed vs Unmanaged Mode","text":"<p>Multi-tenancy in ACA-Py is designed with two key management modes in mind.</p>"},{"location":"features/Multitenancy/#managed-mode","title":"Managed Mode","text":"<p>In <code>managed</code> mode, ACA-Py will manage the key for the wallet. This is the easiest configuration as it allows ACA-Py to fully control the wallet. When a message is received from another agent it can immediately unlock the wallet and process the message. The wallet key is stored encrypted in the base wallet.</p>"},{"location":"features/Multitenancy/#unmanaged-mode","title":"Unmanaged Mode","text":"<p>In <code>unmanaged</code> mode, ACA-Py won't manage the key for the wallet. The key is not stored in the base wallet, which means the key to unlock the wallet needs to be provided whenever the wallet is used. When a message from another agent is received, ACA-Py cannot immediately unlock the wallet and process the message. See Authentication for more info.</p> <p>It is important to note unmanaged mode doesn't provide a lot of security over managed mode. The key is still processed by the agent, and therefore trust is required. It could however provide some benefit in the case a multi-tenant agent is compromised, as the agent doesn't store the key to unlock the wallet.</p> <p> Although support for unmanaged mode is mostly in place, the receiving of messages from other agents in unmanaged mode is not supported yet. This means unmanaged mode can not be used yet.</p>"},{"location":"features/Multitenancy/#mode-usage","title":"Mode Usage","text":"<p>The mode used can be specified when creating a wallet using the <code>key_management_mode</code> parameter.</p> <pre><code>// POST /multitenancy/wallet\n{\n  // ... other params ...\n  \"key_management_mode\": \"managed\" // or \"unmanaged\"\n}\n</code></pre>"},{"location":"features/Multitenancy/#message-routing","title":"Message Routing","text":"<p>In multi-tenant mode, when ACA-Py receives a message from another agent, it will need to determine which tenant to route the message to. Hyperledger Aries defines two types of routing methods, mediation and relaying.</p> <p>See the Mediators and Relays RFC for an in-depth description of the difference between the two concepts.</p>"},{"location":"features/Multitenancy/#relaying","title":"Relaying","text":"<p>In multi-tenant mode, ACA-Py still exposes a single endpoint for each transport. This means it can't route messages to sub wallets based on the endpoint. To resolve this the base wallet acts as a relay for all sub wallets. As can be seen in the architecture diagram above, all messages go through the base wallet. whenever a sub wallet creates a new key or connection, it will be registered at the base wallet. This allows the base wallet to look at the recipient keys for a message and determine which wallet it needs to route to.</p>"},{"location":"features/Multitenancy/#mediation","title":"Mediation","text":"<p>ACA-Py allows messages to be routed through a mediator, and multi-tenancy can be used in combination with external mediators. The following scenarios are possible:</p> <ol> <li>The base wallet has a default mediator set that will be used by sub wallets.</li> <li>Use <code>--mediator-invitation</code> to connect to the mediator, request mediation, and set it as the default mediator</li> <li>Use <code>default-mediator-id</code> if you're already connected to the mediator and mediation is granted (e.g. after restart).</li> <li>When a sub wallet creates a connection or key it will be registered at the mediator via the base wallet connection. The base wallet will still act as a relay and route the messages to the correct sub wallets.</li> <li>Pro: Not every wallet needs to create a connection with the mediator</li> <li>Con: Sub wallets have no control over the mediator.</li> <li>Sub wallet creates a connection with mediator and requests mediation</li> <li>Use mediation as you would in a non-multi-tenant agent, however, the base wallet will still act as a relay.</li> <li>You can set the default mediator to use for connections (using the mediation API).</li> <li>Pro: Sub wallets have control over the mediator.</li> <li>Con: Every wallet</li> </ol> <p>The main tradeoff between option 1. and 2. is redundancy and control. Option 1. doesn't require every sub wallet to create a new connection with the mediator and request mediation. When all sub wallets are going to use the same mediator, this can be a huge benefit. Option 2. gives more control over the mediator being used. This could be useful if e.g. all wallets use a different mediator.</p> <p>A combination of option 1. and 2. is also possible. In this case, two mediators will be used and the sub wallet mediator will forward to the base wallet mediator, which will, in turn, forward to the ACA-Py instance.</p> <pre><code>+---------------------+      +----------------------+      +--------------------+\n| Sub wallet mediator | ---&gt; | Base wallet mediator | ---&gt; | Multi-tenant agent |\n+---------------------+      +----------------------+      +--------------------+\n</code></pre>"},{"location":"features/Multitenancy/#webhooks","title":"Webhooks","text":""},{"location":"features/Multitenancy/#webhook-urls","title":"Webhook URLs","text":"<p>ACA-Py makes use of webhook events to call back to the controller. Multiple webhook targets can be specified, however, in multi-tenant mode, it may be desirable to specify different webhook targets per wallet.</p> <p>When creating a wallet <code>wallet_dispatch_type</code> be used to specify how webhooks for the wallet should be dispatched. The options are:</p> <ul> <li><code>default</code>: Dispatch only to webhooks associated with this wallet.</li> <li><code>base</code>: Dispatch only to webhooks associated with the base wallet.</li> <li><code>both</code>: Dispatch to both webhook targets.</li> </ul> <p>If either <code>default</code> or <code>both</code> is specified you can set the webhook URLs specific to this wallet using the <code>wallet.webhook_urls</code> option.</p> <p>Example:</p> <pre><code>// POST /multitenancy/wallet\n{\n  // ... other params ...\n  \"wallet_dispatch_type\": \"default\",\n  \"wallet_webhook_urls\": [\n    \"https://webhook-url.com/path\",\n    \"https://another-url.com/site\"\n  ]\n}\n</code></pre>"},{"location":"features/Multitenancy/#identifying-the-wallet","title":"Identifying the wallet","text":"<p>When the webhook URLs of the base wallet are used or when multiple wallets specify the same webhook URL it can be hard to identify the wallet an event belongs to. To resolve this each webhook event will include the wallet id the event corresponds to.</p> <p>For HTTP events the wallet id is included as the <code>x-wallet-id</code> header. For WebSockets, the wallet id is included in the enclosing JSON object.</p> <p>HTTP example:</p> <pre><code>POST &lt;webhook-url&gt;/{topic} [headers=x-wallet-id]\n{\n    // event payload\n}\n</code></pre> <p>WebSocket example:</p> <pre><code>{\n  \"topic\": \"{topic}\",\n  \"wallet_id\": \"{wallet_id}\",\n  \"payload\": {\n    // event payload\n  }\n}\n</code></pre>"},{"location":"features/Multitenancy/#authentication","title":"Authentication","text":"<p>When multi-tenancy is not enabled you can authenticate with the agent using the <code>x-api-key</code> header. As there is only a single wallet, this provides sufficient authentication and authorization.</p> <p>For sub wallets, an additional authentication method is introduced using JSON Web Tokens (JWTs). A <code>token</code> parameter is returned after creating a wallet or calling the get token endpoint. This token must be provided for every admin API call you want to perform for the wallet using the Bearer authorization scheme.</p> <p>Example</p> <pre><code>GET /connections [headers=\"Authorization: Bearer {token}]\n</code></pre> <p>The <code>Authorization</code> header is in addition to the Admin API key. So if the <code>admin-api-key</code> is enabled (which should be enabled in production) both the <code>Authorization</code> and the <code>x-api-key</code> headers should be provided when making calls to a sub wallet. For calls to a base wallet, only the <code>x-api-key</code> should be provided.</p>"},{"location":"features/Multitenancy/#getting-a-token","title":"Getting a token","text":"<p>A token can be obtained in two ways. The first method is the <code>token</code> parameter from the response of the create wallet (<code>POST /multitenancy/wallet</code>) endpoint. The second option is using the get wallet token endpoint (<code>POST /multitenancy/wallet/{wallet_id}/token</code>) endpoint.</p>"},{"location":"features/Multitenancy/#method-1-register-new-tenant","title":"Method 1: Register new tenant","text":"<p>This is the method you use to obtain a token when you haven't already registered a tenant.  In this process you will first register a tenant then an object containing your tenant <code>token</code> as well as other useful information like your <code>wallet id</code> will be returned to you.</p> <p>Example</p> <pre><code>new_tenant='{\n  \"image_url\": \"https://aries.ca/images/sample.png\",\n  \"key_management_mode\": \"managed\",\n  \"label\": \"example-label-02\",\n  \"wallet_dispatch_type\": \"default\",\n  \"wallet_key\": \"example-encryption-key-02\",\n  \"wallet_name\": \"example-name-02\",\n  \"wallet_type\": \"askar\",\n  \"wallet_webhook_urls\": [\n    \"https://example.com/webhook\"\n  ]\n}'\n</code></pre> <pre><code>echo $new_tenant | curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"X-Api-Key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d @-\n</code></pre> <p><code>Response</code></p> <pre><code>{\n  \"settings\": {\n    \"wallet.type\": \"askar\",\n    \"wallet.name\": \"example-name-02\",\n    \"wallet.webhook_urls\": [\n      \"https://example.com/webhook\"\n    ],\n    \"wallet.dispatch_type\": \"default\",\n    \"default_label\": \"example-label-02\",\n    \"image_url\": \"https://aries.ca/images/sample.png\",\n    \"wallet.id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\"\n  },\n  \"key_management_mode\": \"managed\",\n  \"updated_at\": \"2022-04-01T15:12:35.474975Z\",\n  \"wallet_id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\",\n  \"created_at\": \"2022-04-01T15:12:35.474975Z\",\n  \"token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ3YWxsZXRfaWQiOiIzYjY0YWQwZC1mNTU2LTRjMDQtOTJiYy1jZDk1YmZkZTU4Y2QifQ.A4eWbSR2M1Z6mbjcSLOlciBuUejehLyytCVyeUlxI0E\"\n}\n</code></pre>"},{"location":"features/Multitenancy/#method-2-get-tenant-token","title":"Method 2: Get tenant token","text":"<p>This method allows you to retrieve a tenant <code>token</code> for an already registered tenant.  To retrieve a token you will need an Admin API key (if your admin is protected with one), <code>wallet_key</code> and the <code>wallet_id</code> of the tenant. Note that calling the get tenant token endpoint will invalidate the old token. This is useful if the old token needs to be revoked, but does mean that you can't have multiple authentication tokens for the same wallet. Only the last generated token will always be valid.</p> <p>Example</p> <pre><code>curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet/{wallet_id}/token\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"X-Api-Key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d { \"wallet_key\": \"example-encryption-key-02\" }\n</code></pre> <p><code>Response</code></p> <pre><code>{\n  \"token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ3YWxsZXRfaWQiOiIzYjY0YWQwZC1mNTU2LTRjMDQtOTJiYy1jZDk1YmZkZTU4Y2QifQ.A4eWbSR2M1Z6mbjcSLOlciBuUejehLyytCVyeUlxI0E\"\n}\n</code></pre> <p>In unmanaged mode, the get token endpoint also requires the <code>wallet_key</code> parameter to be included in the request body. The wallet key will be included in the JWT so the wallet can be unlocked when making requests to the admin API.</p> <pre><code>{\n  \"wallet_id\": \"wallet_id\",\n  // \"wallet_key\" in only present in unmanaged mode\n  \"wallet_key\": \"wallet_key\"\n}\n</code></pre> <p>In unmanaged mode, sending the <code>wallet_key</code> to unlock the wallet in every request is not \u201csecure\u201d but keeps it simple at the moment. Eventually, the authentication method should be pluggable, and unmanaged mode would just mean that the key to unlock the wallet is not managed by ACA-Py.</p>"},{"location":"features/Multitenancy/#jwt-secret","title":"JWT Secret","text":"<p>For deterministic JWT creation and verification between restarts and multiple instances, the same JWT secret would need to be used. Therefore a <code>--jwt-secret</code> param is added to the ACA-Py agent that will be used for JWT creation and verification.</p>"},{"location":"features/Multitenancy/#swaggerui","title":"SwaggerUI","text":"<p>When using the SwaggerUI you can click the  icon next to each of the endpoints or the <code>Authorize</code> button at the top to set the correct authentication headers. Make sure to also include the <code>Bearer</code> part in the input field. This won't be automatically added.</p> <p></p>"},{"location":"features/Multitenancy/#tenant-management","title":"Tenant Management","text":"<p>After registering a tenant which effectively creates a subwallet, you may need to update the tenant information or delete it.  The following describes how to accomplish both goals.</p>"},{"location":"features/Multitenancy/#update-a-tenant","title":"Update a tenant","text":"<p>The following properties can be updated: <code>image_url</code>, <code>label</code>, <code>wallet_dispatch_type</code>, and <code>wallet_webhook_urls</code> for tenants of a multitenancy wallet.  To update these properties you will <code>PUT</code> a request json containing the properties you wish to update along with the updated values to the <code>/multitenancy/wallet/${TENANT_WALLET_ID}</code> admin endpoint.  If the Admin API endpoint is protected, you will also include the Admin API Key in the request header.</p> <p>Example</p> <pre><code>update_tenant='{\n  \"image_url\": \"https://aries.ca/images/sample-updated.png\",\n  \"label\": \"example-label-02-updated\",\n  \"wallet_webhook_urls\": [\n    \"https://example.com/webhook/updated\"\n  ]\n}'\n</code></pre> <pre><code>echo $update_tenant | curl  -X PUT \"${ACAPY_ADMIN_URL}/multitenancy/wallet/${TENANT_WALLET_ID}\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"x-api-key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d @-\n</code></pre> <p><code>Response</code></p> <pre><code>{\n  \"settings\": {\n    \"wallet.type\": \"askar\",\n    \"wallet.name\": \"example-name-02\",\n    \"wallet.webhook_urls\": [\n      \"https://example.com/webhook/updated\"\n    ],\n    \"wallet.dispatch_type\": \"default\",\n    \"default_label\": \"example-label-02-updated\",\n    \"image_url\": \"https://aries.ca/images/sample-updated.png\",\n    \"wallet.id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\"\n  },\n  \"key_management_mode\": \"managed\",\n  \"updated_at\": \"2022-04-01T16:23:58.642004Z\",\n  \"wallet_id\": \"3b64ad0d-f556-4c04-92bc-cd95bfde58cd\",\n  \"created_at\": \"2022-04-01T15:12:35.474975Z\"\n}\n</code></pre> <p>An Admin API Key is all that is ALLOWED to be included in a request header during an update.  Including the Bearer token header will result in a 404: Unauthorized error</p>"},{"location":"features/Multitenancy/#remove-a-tenant","title":"Remove a tenant","text":"<p>The following information is required to delete a tenant:</p> <ul> <li>wallet_id</li> <li>wallet_key</li> <li>{Admin_Api_Key} if admin is protected</li> </ul> <p>Example</p> <pre><code>curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet/{wallet_id}/remove\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"x-api-key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d '{ \"wallet_key\": \"example-encryption-key-02\" }'\n</code></pre> <p><code>Response</code></p> <pre><code>{}\n</code></pre>"},{"location":"features/Multitenancy/#per-tenant-settings","title":"Per tenant settings","text":"<p>To allow the configuring of ACA-Py startup parameters/environment variables at a tenant/subwallet level. PR#2233 will provide the ability to update the following subset of settings when creating or updating the subwallet:</p> Labels Setting ACAPY_LOG_LEVEL log-level log.level ACAPY_INVITE_PUBLIC invite-public debug.invite_public ACAPY_PUBLIC_INVITES public-invites public_invites ACAPY_AUTO_ACCEPT_INVITES auto-accept-invites debug.auto_accept_invites ACAPY_AUTO_ACCEPT_REQUESTS auto-accept-requests debug.auto_accept_requests ACAPY_AUTO_PING_CONNECTION auto-ping-connection auto_ping_connection ACAPY_MONITOR_PING monitor-ping debug.monitor_ping ACAPY_AUTO_RESPOND_MESSAGES auto-respond-messages debug.auto_respond_messages ACAPY_AUTO_RESPOND_CREDENTIAL_OFFER auto-respond-credential-offer debug.auto_respond_credential_offer ACAPY_AUTO_RESPOND_CREDENTIAL_REQUEST auto-respond-credential-request debug.auto_respond_credential_request ACAPY_AUTO_VERIFY_PRESENTATION auto-verify-presentation debug.auto_verify_presentation ACAPY_NOTIFY_REVOCATION notify-revocation revocation.notify ACAPY_AUTO_REQUEST_ENDORSEMENT auto-request-endorsement endorser.auto_request ACAPY_AUTO_WRITE_TRANSACTIONS auto-write-transactions endorser.auto_write ACAPY_CREATE_REVOCATION_TRANSACTIONS auto-create-revocation-transactions endorser.auto_create_rev_reg ACAPY_ENDORSER_ROLE endorser-protocol-role endorser.protocol_role <ul> <li><code>POST /multitenancy/wallet</code></li> </ul> <p>Added <code>extra_settings</code> dict field to request schema. <code>extra_settings</code> can be configured in the request body as below:</p> <p><code>Example Request</code></p> <pre><code>{\n    \"wallet_name\": \" ... \",\n    \"default_label\": \" ... \",\n    \"wallet_type\": \" ... \",\n    \"wallet_key\": \" ... \",\n    \"key_management_mode\": \"managed\",\n    \"wallet_webhook_urls\": [],\n    \"wallet_dispatch_type\": \"base\",\n    \"extra_settings\": {\n        \"ACAPY_LOG_LEVEL\": \"INFO\",\n        \"ACAPY_INVITE_PUBLIC\": true,\n        \"public-invites\": true\n    },\n}\n</code></pre> <pre><code>echo $new_tenant | curl -X POST \"${ACAPY_ADMIN_URL}/multitenancy/wallet\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Api-Key: $ACAPY_ADMIN_URL_API_KEY\" \\\n  -d @-\n</code></pre> <ul> <li><code>PUT /multitenancy/wallet/{wallet_id}</code></li> </ul> <p>Added <code>extra_settings</code> dict field to request schema.</p> <p><code>Example Request</code></p> <pre><code>  {\n    \"wallet_webhook_urls\": [ ... ],\n    \"wallet_dispatch_type\": \"default\",\n    \"label\": \" ... \",\n    \"image_url\": \" ... \",\n    \"extra_settings\": {\n        \"ACAPY_LOG_LEVEL\": \"INFO\",\n        \"ACAPY_INVITE_PUBLIC\": true,\n        \"ACAPY_PUBLIC_INVITES\": false\n    },\n  }\n</code></pre> <pre><code>  echo $update_tenant | curl  -X PUT \"${ACAPY_ADMIN_URL}/multitenancy/wallet/${WALLET_ID}\" \\\n   -H \"Content-Type: application/json\" \\\n   -H \"x-api-key: $ACAPY_ADMIN_URL_API_KEY\" \\\n   -d @-\n</code></pre>"},{"location":"features/PlugIns/","title":"Deeper Dive: Aca-Py Plug-Ins","text":""},{"location":"features/PlugIns/#whats-in-a-plug-in-and-how-does-it-work","title":"What's in a Plug-In and How does it Work?","text":"<p>Plug-ins are loaded on Aca-Py startup based on the following parameters:</p> <ul> <li><code>--plugin</code> - identifies the plug-in library to load</li> <li><code>--block-plugin</code> - identifies plug-ins (including built-ins) that are not to be loaded</li> <li><code>--plugin-config</code> - identify a configuration parameter for a plug-in</li> <li><code>--plugin-config-value</code> - identify a value for a plug-in configuration</li> </ul> <p>The <code>--plug-in</code> parameter specifies a package that is loaded by Aca-Py at runtime, and extends Aca-Py by adding support for additional protocols and message types, and/or extending the Admin API with additional endpoints.</p> <p>The original plug-in design (which we will call the \"old\" model) explicitly included <code>message_types.py</code> <code>routes.py</code> (to add Admin API's).  But functionality was added later (we'll call this the \"new\" model) to allow the plug-in to include a generic <code>setup</code> package that could perform arbitrary initialization.  The \"new\" model also includes support for a <code>definition.py</code> file that can specify plug-in version information  (major/minor plug-in version, as well as the minimum supported version (if another agent is running an older version of the plug-in)).</p> <p>You can discover which plug-ins are installed in an aca-py instance by calling (in the \"server\" section) the <code>GET /plugins</code> endpoint.  (Note that this will return all loaded protocols, including the built-ins.  You can call the <code>GET /status/config</code> to inspect the Aca-Py configuration, which will include the configuration for the external plug-ins.)</p>"},{"location":"features/PlugIns/#setup-method","title":"setup method","text":"<p>If a setup method is provided, it will be called.  If not, the <code>message_types.py</code> and <code>routes.py</code> will be explicitly loaded.</p> <p>This would be in the <code>package/module __init__.py</code>:</p> <pre><code>async def setup(context: InjectionContext):\n    pass\n</code></pre> <p>TODO I couldn't find an implementation of a custom <code>setup</code> in any of the existing plug-ins, so I'm not completely sure what are the best practices for this option.</p>"},{"location":"features/PlugIns/#message_typespy","title":"message_types.py","text":"<p>When loading a plug-in, if there is a <code>message_types.py</code> available, Aca-Py will check the following attributes to initialize the protocol(s):</p> <ul> <li><code>MESSAGE_TYPES</code> - identifies message types supported by the protocol</li> <li><code>CONTROLLERS</code> - identifies protocol controllers</li> </ul>"},{"location":"features/PlugIns/#routespy","title":"routes.py","text":"<p>If <code>routes.py</code> is available, then Aca-Py will call the following functions to initialize the Admin endpoints:</p> <ul> <li><code>register()</code> - registers routes for the new Admin endpoints</li> <li><code>register_events()</code> - registers an events this package will listen for/respond to</li> </ul>"},{"location":"features/PlugIns/#definitionpy","title":"definition.py","text":"<p>If <code>definition.py</code> is available, Aca-Py will read this package to determine protocol version information.  An example follows (this is an example that specifies two protocol versions):</p> <pre><code>versions = [\n    {\n        \"major_version\": 1,\n        \"minimum_minor_version\": 0,\n        \"current_minor_version\": 0,\n        \"path\": \"v1_0\",\n    },\n    {\n        \"major_version\": 2,\n        \"minimum_minor_version\": 0,\n        \"current_minor_version\": 0,\n        \"path\": \"v2_0\",\n    },\n]\n</code></pre> <p>The attributes are:</p> <ul> <li><code>major_version</code> - specifies the protocol major version</li> <li><code>current_minor_version</code> - specifies the protocol minor version</li> <li><code>minimum_minor_version</code> - specifies the minimum supported version (if a lower version is installed in another agent)</li> <li><code>path</code> - specifies the sub-path within the package for this version</li> </ul>"},{"location":"features/PlugIns/#loading-aca-py-plug-ins-at-runtime","title":"Loading Aca-Py Plug-Ins at Runtime","text":"<p>The load sequence for a plug-in (the \"Startup\" class depends on how Aca-Py is running - <code>upgrade</code>, <code>provision</code> or <code>start</code>):</p> <pre><code>sequenceDiagram\n  participant Startup\n  Note right of Startup: Configuration is loaded on startup&lt;br/&gt;from aca-py config params\n    Startup-&gt;&gt;+ArgParse: configure\n    ArgParse-&gt;&gt;settings:  [\"external_plugins\"]\n    ArgParse-&gt;&gt;settings:  [\"blocked_plugins\"]\n\n    Startup-&gt;&gt;+Conductor: setup()\n      Note right of Conductor: Each configured plug-in is validated and loaded\n      Conductor-&gt;&gt;DefaultContext:  build_context()\n      DefaultContext-&gt;&gt;DefaultContext:  load_plugins()\n      DefaultContext-&gt;&gt;+PluginRegistry:  register_package() (for built-in protocols)\n        PluginRegistry-&gt;&gt;PluginRegistry:  register_plugin() (for each sub-package)\n      DefaultContext-&gt;&gt;PluginRegistry:  register_plugin() (for non-protocol built-ins)\n      loop for each external plug-in\n      DefaultContext-&gt;&gt;PluginRegistry:  register_plugin()\n      alt if a setup method is provided\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  has setup\n      else if routes and/or message_types are provided\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  has routes\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  has message_types\n      end\n      opt if definition is provided\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  definition()\n      end\n      end\n      DefaultContext-&gt;&gt;PluginRegistry:  init_context()\n        loop for each external plug-in\n        alt if a setup method is provided\n          PluginRegistry-&gt;&gt;ExternalPlugIn:  setup()\n        else if a setup method is NOT provided\n          PluginRegistry-&gt;&gt;PluginRegistry:  load_protocols()\n          PluginRegistry-&gt;&gt;PluginRegistry:  load_protocol_version()\n          PluginRegistry-&gt;&gt;ProtocolRegistry:  register_message_types()\n          PluginRegistry-&gt;&gt;ProtocolRegistry:  register_controllers()\n        end\n        PluginRegistry-&gt;&gt;PluginRegistry:  register_protocol_events()\n      end\n\n      Conductor-&gt;&gt;Conductor:  load_transports()\n\n      Note right of Conductor: If the admin server is enabled, plug-in routes are added\n      Conductor-&gt;&gt;AdminServer:  create admin server if enabled\n\n    Startup-&gt;&gt;Conductor: start()\n      Conductor-&gt;&gt;Conductor:  start_transports()\n      Conductor-&gt;&gt;AdminServer:  start()\n\n    Note right of Startup: the following represents an&lt;br/&gt;admin server api request\n    Startup-&gt;&gt;AdminServer:  setup_context() (called on each request)\n      AdminServer-&gt;&gt;PluginRegistry:  register_admin_routes()\n      loop for each external plug-in\n        PluginRegistry-&gt;&gt;ExternalPlugIn:  routes.register() (to register endpoints)\n      end</code></pre>"},{"location":"features/PlugIns/#developing-a-new-plug-in","title":"Developing a New Plug-In","text":"<p>When developing a new plug-in:</p> <ul> <li>If you are providing a new protocol or defining message types, you should include a <code>definition.py</code> file.</li> <li>If you are providing a new protocol or defining message types, you should include a <code>message_types.py</code> file.</li> <li>If you are providing additional Admin endpoints, you should include a <code>routes.py</code> file.</li> <li>If you are providing any other functionality, you should provide a <code>setup.py</code> file to initialize the custom functionality.  No guidance is currently available for this option.</li> </ul>"},{"location":"features/PlugIns/#pip-vs-poetry-support","title":"PIP vs Poetry Support","text":"<p>Most Aca-Py plug-ins provide support for installing the plug-in using poetry.  It is recommended to include support in your package for installing using either pip or poetry, to provide maximum support for users of your plug-in.</p>"},{"location":"features/PlugIns/#plug-in-demo","title":"Plug-In Demo","text":"<p>TBD</p>"},{"location":"features/PlugIns/#aca-py-plug-ins","title":"Aca-Py Plug-ins","text":"<p>This list was originally published in this hackmd document.</p> Maintainer Name Features Last Update Link BCGov Redis Events Inbound/Outbound message queue Sep 2022 https://github.com/bcgov/aries-acapy-plugin-redis-events Hyperledger Aries Toolbox UI for ACA-py Aug 2022 https://github.com/hyperledger/aries-toolbox Hyperledger Aries ACApy Plugin Toolbox Protocol Handlers Aug 2022 https://github.com/hyperledger/aries-acapy-plugin-toolbox Indicio Data Transfer Specific Data import Aug 2022 https://github.com/Indicio-tech/aries-acapy-plugin-data-transfer Indicio Question &amp; Answer Non-Aries Protocol Aug 2022 https://github.com/Indicio-tech/acapy-plugin-qa Indicio Acapy-plugin-pickup Fetching Messages from Mediator Aug 2022 https://github.com/Indicio-tech/acapy-plugin-pickup Indicio Machine Readable GF Governance Framework Mar 2022 https://github.com/Indicio-tech/mrgf Indicio Cache Redis Cache for Scalability Jul 2022 https://github.com/Indicio-tech/aries-acapy-cache-redis SICPA Dlab Kafka Events Event Bus Integration Aug 2022 https://github.com/sicpa-dlab/aries-acapy-plugin-kafka-events SICPA Dlab DidComm Resolver Universal Resolver for DIDComm Aug 2022 https://github.com/sicpa-dlab/acapy-resolver-didcomm SICPA Dlab Universal Resolver Multi-ledger Reading Jul 2021 https://github.com/sicpa-dlab/acapy-resolver-universal DDX mydata-did-protocol Oct 2022 https://github.com/decentralised-dataexchange/acapy-mydata-did-protocol BCGov Basic Message Storage Basic message storage (traction) Dec 2022 https://github.com/bcgov/traction/tree/develop/plugins/basicmessage_storage BCGov Multi-tenant Provider Multi-tenant Provider (traction) Dec 2022 https://github.com/bcgov/traction/tree/develop/plugins/multitenant_provider BCGov Traction Innkeeper Innkeeper (traction) Feb 2023 https://github.com/bcgov/traction/tree/develop/plugins/traction_innkeeper"},{"location":"features/PlugIns/#references","title":"References","text":"<p>The following links may be helpful or provide additional context for the current plug-in support.  (These are links to issues or pull requests that were raised during plug-in development.)</p> <p>Configuration params:</p> <ul> <li>https://github.com/hyperledger/aries-cloudagent-python/issues/1121</li> <li>https://hackmd.io/ROUzENdpQ12cz3UB9qk1nA</li> <li>https://github.com/hyperledger/aries-cloudagent-python/pull/1226</li> </ul> <p>Loading plug-ins:</p> <ul> <li>https://github.com/hyperledger/aries-cloudagent-python/pull/1086</li> </ul> <p>Versioning for plug-ins:</p> <ul> <li>https://github.com/hyperledger/aries-cloudagent-python/pull/443</li> </ul>"},{"location":"features/SelectiveDisclosureJWTs/","title":"SD-JWT Implementation in ACA-Py","text":"<p>This document describes the implementation of SD-JWTs in ACA-Py according to the Selective Disclosure for JWTs (SD-JWT) Specification, which defines a mechanism for selective disclosure of individual elements of a JSON object used as the payload of a JSON Web Signature structure.</p> <p>This implementation adds an important privacy-preserving feature to JWTs, since the receiver of an unencrypted JWT can view all claims within. This feature allows the holder to present only a relevant subset of the claims for a given presentation. The issuer includes plaintext claims, called disclosures, outside of the JWT. Each disclosure corresponds to a hidden claim within the JWT. When a holder prepares a presentation, they include along with the JWT only the disclosures corresponding to the claims they wish to reveal. The verifier verifies that the disclosures in fact correspond to claim values within the issuer-signed JWT. The verifier cannot view the claim values not disclosed by the holder.</p> <p>In addition, this implementation includes an optional mechanism for key binding, which is the concept of binding an SD-JWT to a holder's public key and requiring that the holder prove possession of the corresponding private key when presenting the SD-JWT.</p>"},{"location":"features/SelectiveDisclosureJWTs/#issuer-instructions","title":"Issuer Instructions","text":"<p>The issuer determines which claims in an SD-JWT can be selectively disclosable. In this implementation, all claims at all levels of the JSON structure are by default selectively disclosable. If the issuer wishes for certain claims to always be visible, they can indicate which claims should not be selectively disclosable, as described below. Essential verification data such as <code>iss</code>, <code>iat</code>, <code>exp</code>, and <code>cnf</code> are always visible.</p> <p>The issuer creates a list of JSON paths for the claims that will not be selectively disclosable. Here is an example payload:</p> <pre><code>{\n    \"birthdate\": \"1940-01-01\",\n    \"address\": {\n        \"street_address\": \"123 Main St\",\n        \"locality\": \"Anytown\",\n        \"region\": \"Anystate\",\n        \"country\": \"US\",\n    },\n    \"nationalities\": [\"US\", \"DE\", \"SA\"],\n}\n</code></pre> Attribute to access JSON path \"birthdate\" \"birthdate\" The country attribute within the address dictionary \"address.country\" The second item in the nationalities list \"nationalities[1] All items in the nationalities list \"nationalities[0:2]\" <p>The specification defines options for how the issuer can handle nested structures with respect to selective disclosability. As mentioned, all claims at all levels of the JSON structure are by default selectively disclosable.</p>"},{"location":"features/SelectiveDisclosureJWTs/#option-1-flat-sd-jwt","title":"Option 1: Flat SD-JWT","text":"<p>The issuer can decide to treat the <code>address</code> claim in the above example payload as a block that can either be disclosed completely or not at all.</p> <p>The issuer lists out all the claims inside \"address\" in the <code>non_sd_list</code>, but not <code>address</code> itself:</p> <pre><code>non_sd_list = [\n    \"address.street_address\",\n    \"address.locality\",\n    \"address.region\",\n    \"address.country\",\n]\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#option-2-structured-sd-jwt","title":"Option 2: Structured SD-JWT","text":"<p>The issuer may instead decide to make the <code>address</code> claim contents selectively disclosable individually.</p> <p>The issuer lists only \"address\" in the <code>non_sd_list</code>.</p> <pre><code>non_sd_list = [\"address\"]\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#option-3-sd-jwt-with-recursive-disclosures","title":"Option 3: SD-JWT with Recursive Disclosures","text":"<p>The issuer may also decide to make the <code>address</code> claim contents selectively disclosable recursively, i.e., the <code>address</code> claim is made selectively disclosable as well as its sub-claims.</p> <p>The issuer lists neither <code>address</code> nor the subclaims of <code>address</code> in the <code>non_sd_list</code>, leaving all with their default selective disclosability. If all claims can be selectively disclosable, the <code>non_sd_list</code> need not be defined explicitly.</p>"},{"location":"features/SelectiveDisclosureJWTs/#walk-through-of-sd-jwt-implementation","title":"Walk-Through of SD-JWT Implementation","text":""},{"location":"features/SelectiveDisclosureJWTs/#signing-sd-jwts","title":"Signing SD-JWTs","text":""},{"location":"features/SelectiveDisclosureJWTs/#example-input-to-walletsd-jwtsign-endpoint","title":"Example input to <code>/wallet/sd-jwt/sign</code> endpoint","text":"<pre><code>{\n  \"did\": \"WpVJtxKVwGQdRpQP8iwJZy\",\n  \"headers\": {},\n  \"payload\": {\n    \"sub\": \"user_42\",\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\",\n    \"email\": \"johndoe@example.com\",\n    \"phone_number\": \"+1-202-555-0101\",\n    \"phone_number_verified\": true,\n    \"address\": {\n      \"street_address\": \"123 Main St\",\n      \"locality\": \"Anytown\",\n      \"region\": \"Anystate\",\n      \"country\": \"US\"\n    },\n    \"birthdate\": \"1940-01-01\",\n    \"updated_at\": 1570000000,\n    \"nationalities\": [\"US\", \"DE\", \"SA\"],\n    \"iss\": \"https://example.com/issuer\",\n    \"iat\": 1683000000,\n    \"exp\": 1883000000\n  },\n  \"non_sd_list\": [\n    \"given_name\",\n    \"family_name\",\n    \"nationalities\"\n  ]\n}\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#output","title":"Output","text":"<pre><code>\"eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFZERTQSIsICJraWQiOiAiZGlkOnNvdjpXcFZKdHhLVndHUWRScFFQOGl3Slp5I2tleS0xIn0.eyJfc2QiOiBbIkR0a21ha3NkZGtHRjFKeDBDY0kxdmxRTmZMcGFnQWZ1N3p4VnBGRWJXeXciLCAiSlJLb1E0QXVHaU1INWJIanNmNVV4YmJFeDh2YzFHcUtvX0l3TXE3Nl9xbyIsICJNTTh0TlVLNUstR1lWd0swX01kN0k4MzExTTgwVi13Z0hRYWZvRkoxS09JIiwgIlBaM1VDQmdadVRMMDJkV0pxSVY4elUtSWhnalJNX1NTS3dQdTk3MURmLTQiLCAiX294WGNuSW5Yai1SV3BMVHNISU5YaHFrRVAwODkwUFJjNDBISWE1NElJMCIsICJhdnRLVW5Sdnc1clV0TnZfUnAwUll1dUdkR0RzcnJPYWJfVjR1Y05RRWRvIiwgInByRXZJbzBseTVtNTVsRUpTQUdTVzMxWGdVTElOalo5ZkxiRG81U1pCX0UiXSwgImdpdmVuX25hbWUiOiAiSm9obiIsICJmYW1pbHlfbmFtZSI6ICJEb2UiLCAibmF0aW9uYWxpdGllcyI6IFt7Ii4uLiI6ICJPdU1wcEhpYzEySjYzWTBIY2Ffd1BVeDJCTGdUQVdZQjJpdXpMY3lvcU5JIn0sIHsiLi4uIjogIlIxczlaU3NYeVV0T2QyODdEYy1DTVYyMEdvREF3WUVHV3c4ZkVKd1BNMjAifSwgeyIuLi4iOiAid0lJbjdhQlNDVkFZcUF1Rks3Nmpra3FjVGFvb3YzcUhKbzU5WjdKWHpnUSJ9XSwgImlzcyI6ICJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlciIsICJpYXQiOiAxNjgzMDAwMDAwLCAiZXhwIjogMTg4MzAwMDAwMCwgIl9zZF9hbGciOiAic2hhLTI1NiJ9.cIsuGTIPfpRs_Z49nZcn7L6NUgxQumMGQpu8K6rBtv-YRiFyySUgthQI8KZe1xKyn5Wc8zJnRcWbFki2Vzw6Cw~WyJmWURNM1FQcnZicnZ6YlN4elJsUHFnIiwgIlNBIl0~WyI0UGc2SmZ0UnRXdGFPcDNZX2tscmZRIiwgIkRFIl0~WyJBcDh1VHgxbVhlYUgxeTJRRlVjbWV3IiwgIlVTIl0~WyJ4dkRYMDBmalpmZXJpTmlQb2Q1MXFRIiwgInVwZGF0ZWRfYXQiLCAxNTcwMDAwMDAwXQ~WyJYOTlzM19MaXhCY29yX2hudFJFWmNnIiwgInN1YiIsICJ1c2VyXzQyIl0~WyIxODVTak1hM1k3QlFiWUpabVE3U0NRIiwgInBob25lX251bWJlcl92ZXJpZmllZCIsIHRydWVd~WyJRN1FGaUpvZkhLSWZGV0kxZ0Vaal93IiwgInBob25lX251bWJlciIsICIrMS0yMDItNTU1LTAxMDEiXQ~WyJOeWtVcmJYN1BjVE1ubVRkUWVxZXl3IiwgImVtYWlsIiwgImpvaG5kb2VAZXhhbXBsZS5jb20iXQ~WyJlemJwQ2lnVlhrY205RlluVjNQMGJ3IiwgImJpcnRoZGF0ZSIsICIxOTQwLTAxLTAxIl0~WyJvd3ROX3I5Z040MzZKVnJFRWhQU05BIiwgInN0cmVldF9hZGRyZXNzIiwgIjEyMyBNYWluIFN0Il0~WyJLQXktZ0VaWmRiUnNHV1dNVXg5amZnIiwgInJlZ2lvbiIsICJBbnlzdGF0ZSJd~WyJPNnl0anM2SU9HMHpDQktwa0tzU1pBIiwgImxvY2FsaXR5IiwgIkFueXRvd24iXQ~WyI0Nzg5aG5GSjhFNTRsLW91RjRaN1V3IiwgImNvdW50cnkiLCAiVVMiXQ~WyIyaDR3N0FuaDFOOC15ZlpGc2FGVHRBIiwgImFkZHJlc3MiLCB7Il9zZCI6IFsiTXhKRDV5Vm9QQzFIQnhPRmVRa21TQ1E0dVJrYmNrellza1Z5RzVwMXZ5SSIsICJVYkxmVWlpdDJTOFhlX2pYbS15RHBHZXN0ZDNZOGJZczVGaVJpbVBtMHdvIiwgImhsQzJEYVBwT2t0eHZyeUFlN3U2YnBuM09IZ193Qk5heExiS3lPRDVMdkEiLCAia2NkLVJNaC1PaGFZS1FPZ2JaajhmNUppOXNLb2hyYnlhYzNSdXRqcHNNYyJdfV0~\"\n</code></pre> <p>The <code>sd_jwt_sign()</code> method:</p> <ul> <li>Creates the list of claims that are selectively disclosable</li> <li>Uses the <code>non_sd_list</code> compared against the list of JSON paths for all claims to create the list of JSON paths for selectively disclosable claims</li> <li>Separates list splices if necessary</li> <li>Sorts the <code>sd_list</code> so that the claims deepest in the structure are handled first<ul> <li>Since we will wrap the selectively disclosable claim keys, the JSON paths for nested structures do not work properly when the claim key is wrapped in an object</li> </ul> </li> <li>Uses the JSON paths in the <code>sd_list</code> to find each selectively disclosable claim and wrap it in the <code>SDObj</code> defined by the sd-jwt Python library and removes/replaces the original entry</li> <li>For list items, the element itself is wrapped</li> <li>For other objects, the dictionary key is wrapped</li> <li>With this modified payload, the <code>SDJWTIssuerACAPy.issue()</code> method:</li> <li>Checks if there are selectively disclosable claims at any level in the payload</li> <li>Assembles the SD-JWT payload and creates the disclosures</li> <li>Calls <code>SDJWTIssuerACAPy._create_signed_jws()</code>, which is redefined in order to use the ACA-Py <code>jwt_sign</code> method and which creates the JWT</li> <li>Combines and returns the signed JWT with its disclosures and option key binding JWT, as indicated in the specification</li> </ul>"},{"location":"features/SelectiveDisclosureJWTs/#verifying-sd-jwts","title":"Verifying SD-JWTs","text":""},{"location":"features/SelectiveDisclosureJWTs/#example-input-to-walletsd-jwtverify-endpoint","title":"Example input to <code>/wallet/sd-jwt/verify</code> endpoint","text":"<p>Using the output from the <code>/wallet/sd-jwt/sign</code> example above, we have decided to only reveal two of the selectively disclosable claims (<code>user</code> and <code>updated_at</code>) and achieved this by only including the disclosures for those claims. We have also included a key binding JWT following the disclosures.</p> <pre><code>{\n  \"sd_jwt\": \"eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFZERTQSIsICJraWQiOiAiZGlkOnNvdjpXcFZKdHhLVndHUWRScFFQOGl3Slp5I2tleS0xIn0.eyJfc2QiOiBbIkR0a21ha3NkZGtHRjFKeDBDY0kxdmxRTmZMcGFnQWZ1N3p4VnBGRWJXeXciLCAiSlJLb1E0QXVHaU1INWJIanNmNVV4YmJFeDh2YzFHcUtvX0l3TXE3Nl9xbyIsICJNTTh0TlVLNUstR1lWd0swX01kN0k4MzExTTgwVi13Z0hRYWZvRkoxS09JIiwgIlBaM1VDQmdadVRMMDJkV0pxSVY4elUtSWhnalJNX1NTS3dQdTk3MURmLTQiLCAiX294WGNuSW5Yai1SV3BMVHNISU5YaHFrRVAwODkwUFJjNDBISWE1NElJMCIsICJhdnRLVW5Sdnc1clV0TnZfUnAwUll1dUdkR0RzcnJPYWJfVjR1Y05RRWRvIiwgInByRXZJbzBseTVtNTVsRUpTQUdTVzMxWGdVTElOalo5ZkxiRG81U1pCX0UiXSwgImdpdmVuX25hbWUiOiAiSm9obiIsICJmYW1pbHlfbmFtZSI6ICJEb2UiLCAibmF0aW9uYWxpdGllcyI6IFt7Ii4uLiI6ICJPdU1wcEhpYzEySjYzWTBIY2Ffd1BVeDJCTGdUQVdZQjJpdXpMY3lvcU5JIn0sIHsiLi4uIjogIlIxczlaU3NYeVV0T2QyODdEYy1DTVYyMEdvREF3WUVHV3c4ZkVKd1BNMjAifSwgeyIuLi4iOiAid0lJbjdhQlNDVkFZcUF1Rks3Nmpra3FjVGFvb3YzcUhKbzU5WjdKWHpnUSJ9XSwgImlzcyI6ICJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlciIsICJpYXQiOiAxNjgzMDAwMDAwLCAiZXhwIjogMTg4MzAwMDAwMCwgIl9zZF9hbGciOiAic2hhLTI1NiJ9.cIsuGTIPfpRs_Z49nZcn7L6NUgxQumMGQpu8K6rBtv-YRiFyySUgthQI8KZe1xKyn5Wc8zJnRcWbFki2Vzw6Cw~WyJ4dkRYMDBmalpmZXJpTmlQb2Q1MXFRIiwgInVwZGF0ZWRfYXQiLCAxNTcwMDAwMDAwXQ~WyJYOTlzM19MaXhCY29yX2hudFJFWmNnIiwgInN1YiIsICJ1c2VyXzQyIl0~eyJhbGciOiAiRWREU0EiLCAidHlwIjogImtiK2p3dCIsICJraWQiOiAiZGlkOnNvdjpXcFZKdHhLVndHUWRScFFQOGl3Slp5I2tleS0xIn0.eyJub25jZSI6ICIxMjM0NTY3ODkwIiwgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuY29tL3ZlcmlmaWVyIiwgImlhdCI6IDE2ODgxNjA0ODN9.i55VeR7bNt7T8HWJcfj6jSLH3Q7vFk8N0t7Tb5FZHKmiHyLrg0IPAuK5uKr3_4SkjuGt1_iNl8Wr3atWBtXMDA\"\n}\n</code></pre>"},{"location":"features/SelectiveDisclosureJWTs/#verify-output","title":"Verify Output","text":"<p>Note that attributes in the <code>non_sd_list</code> (<code>given_name</code>, <code>family_name</code>, and <code>nationalities</code>), as well as essential verification data (<code>iss</code>, <code>iat</code>, <code>exp</code>) are visible directly within the payload. The disclosures include only the values for the <code>user</code> and <code>updated_at</code> claims, since those are the only selectively disclosable claims that the holder presented. The corresponding hashes for those disclosures appear in the <code>payload[\"_sd\"]</code> list.</p> <pre><code>{\n  \"headers\": {\n    \"typ\": \"JWT\",\n    \"alg\": \"EdDSA\",\n    \"kid\": \"did:sov:WpVJtxKVwGQdRpQP8iwJZy#key-1\"\n  },\n  \"payload\": {\n    \"_sd\": [\n      \"DtkmaksddkGF1Jx0CcI1vlQNfLpagAfu7zxVpFEbWyw\",\n      \"JRKoQ4AuGiMH5bHjsf5UxbbEx8vc1GqKo_IwMq76_qo\",\n      \"MM8tNUK5K-GYVwK0_Md7I8311M80V-wgHQafoFJ1KOI\",\n      \"PZ3UCBgZuTL02dWJqIV8zU-IhgjRM_SSKwPu971Df-4\",\n      \"_oxXcnInXj-RWpLTsHINXhqkEP0890PRc40HIa54II0\",\n      \"avtKUnRvw5rUtNv_Rp0RYuuGdGDsrrOab_V4ucNQEdo\",\n      \"prEvIo0ly5m55lEJSAGSW31XgULINjZ9fLbDo5SZB_E\"\n    ],\n    \"given_name\": \"John\",\n    \"family_name\": \"Doe\",\n    \"nationalities\": [\n      {\n        \"...\": \"OuMppHic12J63Y0Hca_wPUx2BLgTAWYB2iuzLcyoqNI\"\n      },\n      {\n        \"...\": \"R1s9ZSsXyUtOd287Dc-CMV20GoDAwYEGWw8fEJwPM20\"\n      },\n      {\n        \"...\": \"wIIn7aBSCVAYqAuFK76jkkqcTaoov3qHJo59Z7JXzgQ\"\n      }\n    ],\n    \"iss\": \"https://example.com/issuer\",\n    \"iat\": 1683000000,\n    \"exp\": 1883000000,\n    \"_sd_alg\": \"sha-256\"\n  },\n  \"valid\": true,\n  \"kid\": \"did:sov:WpVJtxKVwGQdRpQP8iwJZy#key-1\",\n  \"disclosures\": [\n    [\n      \"xvDX00fjZferiNiPod51qQ\",\n      \"updated_at\",\n      1570000000\n    ],\n    [\n      \"X99s3_LixBcor_hntREZcg\",\n      \"sub\",\n      \"user_42\"\n    ]\n  ]\n}\n</code></pre> <p>The <code>sd_jwt_verify()</code> method:</p> <ul> <li>Parses the SD-JWT presentation into its component parts: JWT, disclosures, and optional key binding</li> <li>The JWT payload is parsed from its headers and signature</li> <li>Creates a list of plaintext disclosures</li> <li>Calls <code>SDJWTVerifierACAPy._verify_sd_jwt</code>, which is redefined in order to use the ACA-Py <code>jwt_verify</code> method, and which returns the verified JWT</li> <li>If key binding is used, the key binding JWT is verified and checked against the expected audience and nonce values</li> </ul>"},{"location":"features/SupportedRFCs/","title":"Aries AIP and RFCs Supported in Aries Cloud Agent Python","text":"<p>This document provides a summary of the adherence of ACA-Py to the Aries Interop Profiles, and an overview of the ACA-Py feature set. This document is manually updated and as such, may not be up to date with the most recent release of ACA-Py or the repository <code>main</code> branch. Reminders (and PRs!) to update this page are welcome! If you have any questions, please contact us on the #aries channel on Hyperledger Discord or through an issue in this repo.</p> <p>Last Update: 2024-03-05, Release 0.12.0rc2</p> <p>The checklist version of this document was created as a joint effort between Northern Block, Animo Solutions and the Ontario government, on behalf of the Ontario government.</p>"},{"location":"features/SupportedRFCs/#aip-support-and-interoperability","title":"AIP Support and Interoperability","text":"<p>See the Aries Agent Test Harness and the Aries Interoperability Status for daily interoperability test run results between ACA-Py and other Aries Frameworks and Agents.</p> AIP Version Supported Notes AIP 1.0 Fully supported. AIP 2.0 Fully supported, with a couple of very minor exceptions noted below. <p>A summary of the Aries Interop Profiles and Aries RFCs supported in ACA-Py can be found later in this document.</p>"},{"location":"features/SupportedRFCs/#platform-support","title":"Platform Support","text":"Platform Supported Notes Server Kubernetes BC Gov has extensive experience running ACA-Py on Red Hat's OpenShift Kubernetes Distribution. Docker Official docker images are published to the GitHub  container repository at <code>ghcr.io/hyperledger/aries-cloudagent-python</code>. Desktop Could be run as a local service on the computer iOS Android Browser"},{"location":"features/SupportedRFCs/#agent-types","title":"Agent Types","text":"Role Supported Notes Issuer Holder Verifier Mediator Service See the aries-mediator-service, a pre-configured, production ready Aries Mediator Service based on a released version of ACA-Py. Mediator Client Indy Transaction Author Indy Transaction Endorser Indy Endorser Service See the aries-endorser-service, a pre-configured, production ready Aries Endorser Service based on a released version of ACA-Py."},{"location":"features/SupportedRFCs/#credential-types","title":"Credential Types","text":"Credential Type Supported Notes Hyperledger AnonCreds Includes full issue VC, present proof, and revoke VC support. W3C Verifiable Credentials Data Model Supports JSON-LD Data Integrity Proof Credentials using the <code>Ed25519Signature2018</code>, <code>BbsBlsSignature2020</code> and <code>BbsBlsSignatureProof2020</code> signature suites.Supports the DIF Presentation Exchange data format for presentation requests and presentation submissions.Work currently underway to add support for Hyperledger AnonCreds in W3C VC JSON-LD Format"},{"location":"features/SupportedRFCs/#did-methods","title":"DID Methods","text":"Method Supported Notes \"unqualified\" Pre-DID standard identifiers. Used either in a peer-to-peer context, or as an alternate form of a <code>did:sov</code> DID published on an Indy network. <code>did:sov</code> <code>did:web</code> Resolution only <code>did:key</code> <code>did:peer</code> Algorithms <code>2</code>/<code>3</code> and <code>4</code> Universal Resolver A plug in from SICPA is available that can be added to an ACA-Py installation to support a universal resolver capability, providing support for most DID methods in the W3C DID Method Registry."},{"location":"features/SupportedRFCs/#secure-storage-types","title":"Secure Storage Types","text":"Secure Storage Types Supported Notes Aries Askar Recommended - Aries Askar provides equivalent/evolved secure storage and cryptography support to the \"indy-wallet\" part of the Indy SDK. When using Askar (via the <code>--wallet-type askar</code> startup parameter), other functionality is handled by CredX (AnonCreds) and Indy VDR (Indy ledger interactions). Aries Askar-AnonCreds Recommended - When using Askar/AnonCreds (via the <code>--wallet-type askar-anoncreds</code> startup parameter), other functionality is handled by AnonCreds RS (AnonCreds) and Indy VDR (Indy ledger interactions).This <code>wallet-type</code> will eventually be the same as <code>askar</code> when we have fully integrated the AnonCreds RS library into ACA-Py. Indy SDK  Deprecated Full support for the features of the \"indy-wallet\" secure storage capabilities found in the Indy SDK. <p>New installations of ACA-Py should NOT use the Indy SDK. Existing deployments using the Indy SDK should transition to Aries Askar and related components as soon as possible.</p>"},{"location":"features/SupportedRFCs/#miscellaneous-features","title":"Miscellaneous Features","text":"Feature Supported Notes ACA-Py Plugins The ACA-Py Plugins repository contains a growing set of plugins that are maintained and (mostly) tested against new releases of ACA-Py. Multi use invitations Invitations using public did Implicit pickup of messages in role of mediator Revocable AnonCreds Credentials Multi-Tenancy Documentation Multi-Tenant Management The Traction open source project from BC Gov is a layer on top of ACA-Py that enables the easy management of ACA-Py tenants, with an Administrative UI (\"The Innkeeper\") and a Tenant UI for using ACA-Py in a web UI (setting up, issuing, holding and verifying credentials) Connection-less (non OOB protocol / AIP 1.0) Only for issue credential and present proof Connection-less (OOB protocol / AIP 2.0) Only for present proof Signed Attachments Used for OOB Multi Indy ledger support (with automatic detection) Support added in the 0.7.3 Release. Persistence of mediated messages Plugins in the ACA-Py Plugins repository are available for persistent queue support using Redis and Kafka. Without persistent queue support, messages are stored in an in-memory queue and so are subject to loss in the case of a sudden termination of an ACA-Py process. The in-memory queue is properly handled in the case of a graceful shutdown of an ACA-Py process (e.g. processing of the queue completes and no new messages are accepted). Storage Import &amp; Export Supported by directly interacting with the Aries Askar (e.g., no Admin API endpoint available for wallet import &amp; export). Aries Askar support includes the ability to import storage exported from the Indy SDK's \"indy-wallet\" component. Documentation for migrating from Indy SDK storage to Askar can be found in the Indy SDK to Askar Migration Guide. SD-JWTs Signing and verifying SD-JWTs is supported"},{"location":"features/SupportedRFCs/#supported-rfcs","title":"Supported RFCs","text":""},{"location":"features/SupportedRFCs/#aip-10","title":"AIP 1.0","text":"<p>All RFCs listed in AIP 1.0 are fully supported in ACA-Py. The following table provides notes about the implementation of specific RFCs.</p> RFC Supported Notes 0025-didcomm-transports ACA-Py currently supports HTTP and WebSockets for both inbound and outbound messaging. Transports are pluggable and an agent instance can use multiple inbound and outbound transports. 0160-connection-protocol The agent supports Connection/DID exchange initiated from both plaintext invitations and public DIDs that enable bypassing the invitation message."},{"location":"features/SupportedRFCs/#aip-20","title":"AIP 2.0","text":"<p>All RFCs listed in AIP 2.0 (including the sub-targets) are fully supported in ACA-Py EXCEPT as noted in the table below.</p> RFC Supported Notes 0587-encryption-envelope-v2 Supporting the DIDComm v2 encryption envelope does not make sense until DIDComm v2 is to be supported. 0317-please-ack An investigation was done into supporting <code>please-ack</code> and a number of complications were found. As a result, we expect that <code>please-ack</code> will be dropped from AIP 2.0. It has not been implemented by any Aries frameworks or deployments. <p>There is a PR to the Aries RFCs repository to remove those RFCs from AIP 2.0. If that PR is removed, the RFCs will be removed from the table above.</p>"},{"location":"features/SupportedRFCs/#other-supported-rfcs","title":"Other Supported RFCs","text":"RFC Supported Notes 0031-discover-features Rarely (never?) used, and in implementing the V2 version of the protocol, the V1 version was found to be incomplete and was updated as part of Release 0.7.3 0028-introduce 00509-action-menu"},{"location":"features/UsingOpenAPI/","title":"Aries Cloud Agent-Python (ACA-Py) - OpenAPI Code Generation Considerations","text":"<p>ACA-Py provides an OpenAPI-documented REST interface for administering the agent's internal state and initiating communication with connected agents.</p> <p>The running agent provides a <code>Swagger User Interface</code> that can be browsed and used to test various scenarios manually (see the Admin API Readme for details). However, it is often desirable to produce native language interfaces rather than coding <code>Controllers</code> using HTTP primitives. This is possible using several public code generation (codegen) tools. This page provides some suggestions based on experience with these tools when trying to generate <code>Typescript</code> wrappers. The information should be useful to those trying to generate other languages. Updates to this page based on experience are encouraged.</p>"},{"location":"features/UsingOpenAPI/#aca-py-openapi-raw-output-characteristics","title":"ACA-Py, OpenAPI Raw Output Characteristics","text":"<p>ACA-Py uses aiohttp_apispec tags in code to produce the OpenAPI spec file at runtime dependent on what features have been loaded. How these tags are created is documented in the API Standard Behavior section of the Admin API Readme. The OpenAPI spec is available in raw, unformatted form from a running ACA-Py instance using a route of <code>http://&lt;acapy host and port&gt;/api/docs/swagger.json</code> or from the browser <code>Swagger User Interface</code> directly.</p> <p>The ACA-Py Admin API evolves across releases. To track these changes and ensure conformance with the OpenAPI specification, we provide a tool located at <code>scripts/generate-open-api-spec</code>. This tool starts ACA-Py, retrieves the <code>swagger.json</code> file, and runs codegen tools to generate specifications in both Swagger and OpenAPI formats with <code>json</code> language output. The output of this tool enables comparison with the checked-in <code>open-api/swagger.json</code> and <code>open-api/openapi.json</code>, and also serves as a useful resource for identifying any non-conformance to the OpenAPI specification. At the moment, <code>validation</code> is turned off via the <code>open-api/openAPIJSON.config</code> file, so warning messages are printed for non-conformance, but the <code>json</code> is still output. Most of the warnings reported by <code>generate-open-api-spec</code> relate to missing <code>operationId</code> fields which results in manufactured method names being created by codegen tools. At the moment, aiohttp_apispec does not support adding <code>operationId</code> annotations via tags.</p> <p>The <code>generate-open-api-spec</code> tool was initially created to help identify issues with method parameters not being sorted, resulting in somewhat random ordering each time a codegen operation was performed. This is relevant for languages which do not have support for named parameters such as <code>Javascript</code>. It is recommended that the <code>generate-open-api-spec</code> is run prior to each release, and the resulting <code>open-api/openapi.json</code> file checked in to allow tracking of API changes over time. At the moment, this process is not automated as part of the release pipeline.</p>"},{"location":"features/UsingOpenAPI/#generating-language-wrappers-for-aca-py","title":"Generating Language Wrappers for ACA-Py","text":"<p>There are inevitably differences around <code>best practice</code> for method naming based on coding language and organization standards.</p> <p>Best practice for generating ACA-Py language wrappers is to obtain the raw OpenAPI file from a configured/running ACA-Py instance and then post-process it with a merge utility to match routes and insert desired <code>operationId</code> fields. This allows the greatest flexibility in conforming to external naming requirements.</p> <p>Two major open-source code generation tools are Swagger and OpenAPI Tools. Which of these to use can be very dependent on language support required and preference for the style of code generated.</p> <p>The OpenAPI Tools was found to offer some nice features when generating <code>Typescript</code>. It creates separate files for each class and allows the use of a <code>.openapi-generator-ignore</code> file to override generation if there is a spec file issue that needs to be maintained manually.</p> <p>If generating code for languages that do not support named parameters, it is recommended to specify the <code>useSingleRequestParameter</code> or equivalent in your code generator of choice. The reason is that, as mentioned previously, there have been instances where parameters were not sorted when output into the raw ACA-Py API spec file, and this approach helps remove that risk.</p> <p>Another suggestion for code generation is to keep the <code>modelPropertyNaming</code> set to <code>original</code> when generating code. Although it is tempting to try and enable marshaling into standard naming formats such as <code>camelCase</code>, the reality is that the models represent what is sent on the wire and documented in the Aries Protocol RFCS. It has proven handy to be able to see code references correspond directly with protocol RFCs when debugging. It will also correspond directly with what the <code>model</code> shows when looking at the ACA-Py <code>Swagger UI</code> in a browser if you need to try something out manually before coding. One final point is that on occasions, it has been discovered that the code generation tools don't always get the marshaling correct in all circumstances when changing model name format.</p>"},{"location":"features/UsingOpenAPI/#existing-language-wrappers-for-aca-py","title":"Existing Language Wrappers for ACA-Py","text":""},{"location":"features/UsingOpenAPI/#python","title":"Python","text":"<ul> <li>Aries Cloud Controller Python (GitHub / didx-xyz)</li> <li>Aries Cloud Controller (PyPi)</li> <li>Traction (GitHub / bcgov)</li> <li>acapy-client (GitHub / Indicio-tech)</li> </ul>"},{"location":"features/UsingOpenAPI/#go","title":"Go","text":"<ul> <li>go-acapy-client (GitHub / Idej)</li> </ul>"},{"location":"features/UsingOpenAPI/#java","title":"Java","text":"<ul> <li>ACA-Py Java Client Library (GitHub / hyperledger-labs)</li> </ul>"},{"location":"features/devcontainer/","title":"ACA-Py Development with Dev Container","text":"<p>The following guide will get you up and running and developing/debugging ACA-Py as quickly as possible. We provide a <code>devcontainer</code> and will use <code>VS Code</code> to illustrate.</p> <p>By no means is ACA-Py limited to these tools; they are merely examples.  </p> <p>For information on running demos and tests using provided shell scripts, see DevReadMe readme.</p>"},{"location":"features/devcontainer/#caveats","title":"Caveats","text":"<p>The primary use case for this <code>devcontainer</code> is for developing, debugging and unit testing (pytest) the aries_cloudagent source code.</p> <p>There are limitations running this devcontainer, such as all networking is within this container. This container has docker-in-docker which allows running demos, building docker images, running <code>docker compose</code> all within this container.</p>"},{"location":"features/devcontainer/#files","title":"Files","text":"<p>The <code>.devcontainer</code> folder contains the <code>devcontainer.json</code> file which defines this container. We are using a <code>Dockerfile</code> and <code>post-install.sh</code> to build and configure the container run image. The <code>Dockerfile</code> is simple but in place for simplifying image enhancements (ex. adding <code>poetry</code> to the image). The <code>post-install.sh</code> will install some additional development libraries (including for BDD support).</p>"},{"location":"features/devcontainer/#devcontainer","title":"Devcontainer","text":"<p>What are Development Containers?</p> <p>A Development Container (or Dev Container for short) allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.</p> <p>see https://containers.dev.</p> <p>In this guide, we will use Docker and Visual Studio Code with the Dev Containers Extension installed, please set your machine up with those. As of writing, we used the following:</p> <ul> <li>Docker Version: 20.10.24</li> <li>VS Code Version: 1.79.0</li> <li>Dev Container Extension Version: v0.295.0</li> </ul>"},{"location":"features/devcontainer/#open-aca-py-in-the-devcontainer","title":"Open ACA-Py in the devcontainer","text":"<p>To open ACA-Py in a devcontainer, we open the root of this repository. We can open in 2 ways:</p> <ol> <li>Open Visual Studio Code, and use the Command Palette and use <code>Dev Containers: Open Folder in Container...</code></li> <li>Open Visual Studio Code and <code>File|Open Folder...</code>, you should be prompted to <code>Reopen in Container</code>.</li> </ol> <p>NOTE follow any prompts to install <code>Python Extension</code> or reload window for <code>Pylance</code> when first building the container.</p> <p>ADDITIONAL NOTE we advise that after each time you rebuild the container that you also perform: <code>Developer: Reload Window</code> as some extensions seem to require this in order to work as expected.</p>"},{"location":"features/devcontainer/#devcontainerjson","title":"devcontainer.json","text":"<p>When the .devcontainer/devcontainer.json is opened, you will see it building... it is building a Python 3.9 image (bash shell) and loading it with all the ACA-Py requirements (and black). We also load a few Visual Studio settings (for running Pytests and formatting with Flake and Black).</p>"},{"location":"features/devcontainer/#poetry","title":"Poetry","text":"<p>The Python libraries / dependencies are installed using <code>poetry</code>. For the devcontainer, we DO NOT use virtual environments. This means you will not see or need venv prompts in the terminals and you will not need to run tasks through poetry (ie. <code>poetry run black .</code>). If you need to add new dependencies, you will need to add the dependency via poetry AND you should rebuild your devcontainer.</p> <p>In VS Code, open a Terminal, you should be able to run the following commands:</p> <pre><code>python -m aries_cloudagent -v\ncd aries_cloudagent\nruff check .\nblack . --check\npoetry --version\n</code></pre> <p>The first command should show you that <code>aries_cloudagent</code> module is loaded (ACA-Py). The others are examples of code quality checks that ACA-Py does on commits (if you have <code>precommit</code> installed) and Pull Requests.</p> <p>When running <code>ruff check .</code> in the terminal, you may see <code>error: Failed to initialize cache at /.ruff_cache: Permission denied (os error 13)</code> - that's ok. If there are actual ruff errors, you should see something like:</p> <pre><code>error: Failed to initialize cache at /.ruff_cache: Permission denied (os error 13)\nadmin/base_server.py:7:7: D101 Missing docstring in public class\nFound 1 error.\n</code></pre>"},{"location":"features/devcontainer/#extensions","title":"extensions","text":"<p>We have added Black formatter and Ruff extensions. Although we have added launch settings for both <code>ruff</code> and <code>black</code>, you can also use the extension commands from the command palette.</p> <ul> <li><code>Ruff: Format Document</code></li> <li><code>Ruff: Fix all auto-fixable problems</code></li> </ul> <p>More importantly, these extensions are now added to document save, so files will be formatted and checked. We advise that after each time you rebuild the container that you also perform: <code>Developer: Reload Window</code> to ensure the extensions are loaded correctly.</p>"},{"location":"features/devcontainer/#running-docker-in-docker-demos","title":"Running docker-in-docker demos","text":"<p>Start by running a von-network inside your dev container. Or connect to a hosted ledger. You will need to adjust the ledger configurations if you do this.</p> <pre><code>git clone https://github.com/bcgov/von-network\ncd von-network\n./manage build\n./manage start\ncd ..\n</code></pre> <p>If you want to have revocation then start up a tails server in your dev container. Or connect to a hosted tails server. Once again you will need to adjust the configurations.</p> <pre><code>git clone https://github.com/bcgov/indy-tails-server.git\ncd indy-tails-server/docker\n./manage build\n./manage start\ncd ../..\n</code></pre> <pre><code># open a terminal in VS Code...\ncd demo\n./run_demo faber\n# open a second terminal in VS Code...\ncd demo\n./run_demo alice\n# follow the script...\n</code></pre>"},{"location":"features/devcontainer/#further-reading-and-links","title":"Further Reading and Links","text":"<ul> <li>Development Containers (devcontainers): https://containers.dev</li> <li>Visual Studio Code: https://code.visualstudio.com</li> <li>Dev Containers Extension: marketplace.visualstudio.com</li> <li>Docker: https://www.docker.com</li> <li>Docker Compose: https://docs.docker.com/compose/</li> </ul>"},{"location":"features/devcontainer/#aca-py-debugging","title":"ACA-Py Debugging","text":"<p>To better illustrate debugging pytests and ACA-Py runtime code, let's add some run/debug configurations to VS Code. If you have your own <code>launch.json</code> and <code>settings.json</code>, please cut and paste what you want/need.</p> <pre><code>cp -R .vscode-sample .vscode\n</code></pre> <p>This will add a <code>launch.json</code>, <code>settings.json</code> and multiple ACA-Py configuration files for developing with different scenarios.</p> <ul> <li>Faber: Simple agent to simulate an issuer</li> <li>Alice: Simple agent to simulate a holder</li> <li>Endorser: Simulates the endorser agent in an endorsement required environment</li> <li>Author: Simulates an author agent in a endorsement required environment</li> <li>Multitenant Admin: Includes settings for a multitenant/wallet scenario</li> </ul> <p>Having multiple agents is to demonstrate launching multiple agents in a debug session. Any of the config files and the launch file can be changed and customized to meet your needs. They are all setup to run on different ports so they don't interfere with each other. Running the debug session from inside the dev container allows you to contact other services such as a local ledger or tails server using localhost, while still being able to access the swagger admin api through your browser.</p> <p>For all the agents if you want to use another ledger (von-network) other than localhost you will need to change the <code>genesis-url</code> config. For all the agents if you don't want to support revocation you need to remove or comment out the <code>tails-server-base-url</code> config. If you want to use a non localhost server then you will need to change the url.</p>"},{"location":"features/devcontainer/#faber","title":"Faber","text":"<ul> <li>admin api url = http://localhost:9041</li> <li>study the demo to understand the steps to have the agent in the correct state. Make your public dids and schemas, cred-defs, etc.</li> </ul>"},{"location":"features/devcontainer/#alice","title":"Alice","text":"<ul> <li>admin api url = http://localhost:9011</li> <li>study the demo to get a connection with faber</li> </ul>"},{"location":"features/devcontainer/#endorser","title":"Endorser","text":"<ul> <li>admin api url = http://localhost:9031</li> <li>This config is useful if you want to develop in an environment that requires endorsement. You can run the demo with <code>./run_demo faber --endorser-role author</code> to see all the steps to become and endorser.</li> </ul>"},{"location":"features/devcontainer/#author","title":"Author","text":"<ul> <li>admin api url = http://localhost:9021</li> <li>This config is useful if you want to develop in an environment that requires endorsement. You can run the demo with <code>./run_demo faber --endorser-role author</code> to see all the steps to become and author. You need to uncomment the configurations for automating the connection to endorser.</li> </ul>"},{"location":"features/devcontainer/#multitenant-admin","title":"Multitenant-Admin","text":"<ul> <li>admin api url = http://localhost:9051</li> <li>This is for a multitenant environment where you can create multiple tenants with subwallets with one agent. See Multitenancy</li> </ul>"},{"location":"features/devcontainer/#try-running-faber-and-alice-at-the-same-time-and-add-break-points-and-recreate-the-demo","title":"Try running Faber and Alice at the same time and add break points and recreate the demo","text":"<p>To run your ACA-Py code in debug mode, go to the <code>Run and Debug</code> view, select the agent(s) you want to start and click <code>Start Debugging (F5)</code>.</p> <p>This will start your source code as a running ACA-Py instance, all configuration is in the <code>*.yml</code> files. This is just a sample of a configuration. Note that we are not using a database and are joining to a local VON Network (by default, it would be <code>http://localhost:9000</code>). You could change this or another ledger such as <code>http://test.bcovrin.vonx.io</code>. These are purposefully, very simple configurations.</p> <p>For example, open <code>aries_cloudagent/admin/server.py</code> and set a breakpoint in <code>async def status_handler(self, request: web.BaseRequest):</code>, then call <code>GET /status</code> in the Admin Console and hit your breakpoint.</p>"},{"location":"features/devcontainer/#pytest","title":"Pytest","text":"<p>Pytest is installed and almost ready; however, we must build the test list. In the Command Palette, <code>Test: Refresh Tests</code> will scan and find the tests.</p> <p>See Python Testing for more details, and Test Commands for usage.</p> <p>WARNING: our pytests include coverage, which will prevent the debugger from working. One way around this would be to have a <code>.vscode/settings.json</code> that says not to use coverage (see above). This will allow you to set breakpoints in the pytest and code under test and use commands such as <code>Test: Debug Tests in Current File</code> to start debugging.</p> <p>WARNING: the project configuration found in <code>pyproject.toml</code> include performing <code>ruff</code> checks when we run <code>pytest</code>. Including <code>ruff</code> does not play nice with the Testing view. In order to have our pytests discoverable AND available in the Testing view, we create a <code>.pytest.ini</code> when we build the devcontainer. This file will not be committed to the repo, nor does it impact <code>./scripts/run_tests</code> but it will impact if you manually run the pytest commands locally outside of the devcontainer. Just be aware that the file will stay on your file system after you shutdown the devcontainer.</p>"},{"location":"features/devcontainer/#next-steps","title":"Next Steps","text":"<p>At this point, you now have a development environment where you can add pytests, add ACA-Py code and run and debug it all. Be aware there are limitations with <code>devcontainer</code> and other docker networks. You may need to adjust other docker-compose files not to start their own networks, and you may need to reference containers using <code>host.docker.internal</code>. This isn't a panacea but should get you going in the right direction and provide you with some development tools.</p>"},{"location":"gettingStarted/","title":"Becoming an Indy/Aries Developer","text":"<p>This guide is to get you from (pretty much) zero to developing code for issuing (and verifying) credentials with your own Aries agent. On the way, you'll look at Hyperledger Indy and how it works, find out about the architecture and components of an Aries agent and its underlying messaging protocols. Scan the list of topics below and jump in as soon as you hit a topic you don't know.</p> <p>Note that in the guidance we have here, we include not only the links to look at, but we recommend that you not look at certain material to which you might naturally gravitate. That's because the material is out of date and will take you down some unnecessary rabbit holes. Keep your eyes on the goal - developing with Aries to interact with other agents to (amongst other things) connect, issue, hold, present and verify verifiable credentials.</p> <ul> <li>I've heard of Indy, but I don't know the basics</li> <li>I know about Indy, but what is Aries?</li> <li>Demos - Business Level</li> <li>Aries Agents in Context: The Big Picture</li> <li>Aries Internals - Deployment Components</li> <li>An overview of Aries messaging</li> <li>Demos - Aries Developer</li> <li>Establishing a connection between Aries Agents</li> <li>Issuing an AnonCreds credential: From Issuer to Holder/Prover</li> <li>Presenting an Indy credential: From Holder/Prover to Verifier</li> <li>Next steps: Creating your own Aries Agent</li> <li>What should I work on? Options for Aries/Indy Developers</li> <li>Deeper Dive: DIDComm Messages</li> <li>Deeper Dive: DIDComm Message Routing and Encryption</li> <li>Deeper Dive: Routing Example</li> <li>To Do: Deeper Dive: Running and Connecting to an Indy Network</li> <li>Steps and APIs to support credential revocation with Aries agent</li> <li>Deeper Dive: Aca-Py Plug-Ins</li> </ul> <p>Want to help with this guide? Please add issues or submit a pull request to improve the document. Point out things that are missing, things to improve and especially things that are wrong.</p>"},{"location":"gettingStarted/AgentConnections/","title":"Establishing a connection between Aries Agents","text":"<p>Use an ACA-Py issuer/verifier to establish a connection with an Aries mobile wallet. Run the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/AriesAgentArchitecture/","title":"Aries Cloud Agent Internals: Agent and Controller","text":"<p>This section talks in particular about the architecture of this Aries cloud agent implementation. An instance of an Aries agent is actually made up of to two parts - the agent itself and a controller.</p> <p></p> <p>The agent handles all of the core Aries functionality such as interacting with other agents, managing secure storage, sending event notifications to, and receiving directions from, the controller. The controller provides the business logic that defines how that particular agent instance behaves--how to respond to events in the agent, and when to trigger the agent to initiate events. The controller might be a web or native user interface for a person or it might be coded business rules driven by an enterprise system.</p> <p>Between the two is a simple interface. The agent sends event notifications to the controller and the controller sends administrator messages to the agent. The controller registers a webhook with the agent, and the event notifications are HTTP callbacks, and the agent exposes a REST API to the controller for all of the administrative messages it is configured to handle. Each of the DIDComm protocols supported by the agent adds a set of administrative messages for the controller to use in responding to events. The Aries cloud agent includes an OpenAPI (aka Swagger) user interface for a developer to use to explore the API for a specific agent.</p> <p>As such, the agent is just a configured dependency in an Aries cloud agent deployment. Thus, the vast majority of Aries developers will focus on building controllers (business logic) and perhaps some custom plugins (protocols, as we'll discuss soon) for the agent. Only a relatively small group of Aries cloud agent maintainers will focus on adding and maintaining the agent dependency.</p> <p>Want more details about the agent and controller internals? Take a look at the Aries cloud agent deployment model document.</p> <p>Back to the Aries Developer - Getting Started Guide. </p>"},{"location":"gettingStarted/AriesBasics/","title":"What is Aries?","text":"<p>Hyperledger Aries provides a shared, reusable, interoperable tool kit designed for initiatives and solutions focused on creating, transmitting and storing verifiable digital credentials. It is infrastructure for blockchain-rooted, peer-to-peer interactions. It includes a shared cryptographic wallet for blockchain clients as well as a communications protocol for allowing off-ledger interaction between those clients.  </p> <p>A Hyperledger Aries agent (such as the one in this repository):</p> <ul> <li>enables establishing connections with other DIDComm-based agents (using DIDComm encryption envelopes),</li> <li>exchanges messages between connected agents to execute message protocols (using DIDComm protocols)</li> <li>sends notifications about protocol events to a controller, and</li> <li>exposes an API for responses from the controller with direction in handling protocol events.</li> </ul> <p>The concepts and features that make up the Aries project are documented in the aries-rfcs - but don't dive in there yet! We'll get to the features and concepts to be found there with a guided tour of the key RFCs. The Aries Working Group meets weekly to expand the design and components of Aries.</p> <p>The Aries Cloud Agent Python currently only supports Hyperledger Indy-based verifiable credentials and public ledger. Longer term (as we'll see later in this guide) protocols will be extended or added to support other verifiable credential implementations and public ledgers.</p> <p>Back to the Aries Developer - Getting Started Guide. </p>"},{"location":"gettingStarted/AriesBigPicture/","title":"Aries Agents in context: The Big Picture","text":"<p>Aries agents can be used in a lot of places. This classic Indy Architecture picture shows five agents - the four around the outside (on a phone, a tablet, a laptop and an enterprise server) are referred to as \"edge agents\", and many cloud agents in the blue circle.</p> <p></p> <p>The agents in the picture shares many attributes:</p> <ul> <li>They have some sort of storage for keys and other data related to their role as an agent</li> <li>They interact with other agents using secure. peer-to-peer messaging protocols</li> <li>They have some associated mechanism to provide \"business rules\" to control the behavior of the agent</li> <li>That is often a person for phone, tablet, laptop, etc. based agents</li> <li>That is often backend enterprise systems for enterprise agents</li> <li>Business rules for cloud agents are often about the routing of messages to and from edge agents</li> </ul> <p>While there can be many other agent setups, the picture above shows the most common ones - edge agents for people, edge agents for organizations and cloud agents for routing messages (although cloud agents could be edge agents. Sigh...). A significant emerging use case missing from that picture are agents embedded within/associated with IoT devices. In the common IoT case, IoT device agents are just variants of other edge agents, connected to the rest of the ecosystem through a cloud agent. All the same principles apply.</p> <p>Misleading in the picture is that (almost) all agents connect directly to the Ledger network. In this picture it's the Sovrin ledger, but that could be any Indy network (e.g. set of nodes running indy-node software) and in future, ledgers from other providers. That implies most agents embed the ledger SDK (e.g. indy-sdk) and makes calls to the ledger SDK to interact with the ledger and other SDK controlled resources (e.g. secure storage). Thus, unlike what is implied in the picture, edge agents (commonly) do not call a cloud agent to interact with the ledger - they do it directly. Super small IoT devices are an instance of an exception to that - lacking compute/storage resources and/or connectivity, they might communicate with a cloud agent that would communicate with the ledger.</p> <p>While current Aries agents currently only support Indy-based ledgers, the intention is to add support for other ledgers.</p> <p>The (most common) purpose of cloud agents is to enable secure and privacy preserving routing of messages between edge agents. Rather than messages going directly from edge agent to edge agent (which is often impossible - for example sending to a mobile agent), messages sent from edge agent to edge agent are routed through a sequence of cloud agents. Some of those cloud agents might be controlled by the sender, some by the receiver and others might be gateways owned by agent vendors (called \"Agencies\"). In all cases, an edge agent tells routing agents \"here's how to send messages to me\", so a routing agent sending a message only has to know how to send a peer-to-peer message. While quite complicated, the protocols used by the agents largely take care of this complexity, and most developers don't have to know much about it.</p> <p>Note the many caveats in this section - \"most common\", \"commonly\", etc. There are many small building blocks available in Aries and underlying components that can be combined in infinite ways. We recommend not worrying about the alternate use cases for now. Focus on understanding the common use cases while remembering that other configurations are possible.</p> <p>We also recommend not digging into all the layers described here. Just as you don't have to know how TCP/IP works to write a web app, you don't need to know how indy-node or indy-sdk work to be able to build your first Aries-based application. Later in this guide we'll covering the starting point you do need to know.</p> <p>Back to the Aries Developer - Getting Started Guide.</p>"},{"location":"gettingStarted/AriesDeveloperDemos/","title":"Developer Demos and Samples of Aries Agent","text":"<p>Here are some demos that developers can use to get up to speed on Aries. You don't have to be a developer to use these. If you can use docker and JSON, then that's enough to give these a try.</p>"},{"location":"gettingStarted/AriesDeveloperDemos/#open-api-demo","title":"Open API demo","text":"<p>This demo uses agents (and an Indy ledger), but doesn't implement a controller at all. Instead it uses the OpenAPI (aka Swagger) user interface to let you be the controller to connect agents, issue a credential and then proof that credential.</p> <p>Collaborating Agents OpenAPI Demo</p>"},{"location":"gettingStarted/AriesDeveloperDemos/#python-controller-demo","title":"Python Controller demo","text":"<p>Run this demo to see a couple of simple Python controller implementations for Alice and Faber. Like the previous demo, this shows the agents connecting, Faber issuing a credential to Alice and then requesting a proof based on the credential. Running the demo is simple, but there's a lot for a developer to learn from the code.</p> <p>Python-based Alice/Faber Demo</p>"},{"location":"gettingStarted/AriesDeveloperDemos/#mobile-app-and-web-sample-bc-gov-showcase","title":"Mobile App and Web Sample - BC Gov Showcase","text":"<p>Try out the BC Gov Showcase to download a production Wallet for holding Verifiable Credentials, and then use your new wallet to get and present credentials in some sample scenarios. The end-to-end verifiable credential experience in 30 minutes or less.</p>"},{"location":"gettingStarted/AriesMessaging/","title":"An overview of Aries messaging","text":"<p>Aries Agents communicate with each other via a message mechanism called DIDComm (DID Communication). DIDComm enables secure, asynchronous, end-to-end encrypted messaging between agents, with messages (usually) routed through some configuration of intermediary agents. Aries agents use (an early instance of) the did:peer DID method, which uses DIDs that are not published to a public ledger, but only shared privately between the communicating parties - usually just two agents.</p> <p>Given the underlying secure messaging layer (routing and encryption covered later in the \"Deeper Dive\" sections), DIDComm protocols define standard sets of messages to accomplish a task. For example:</p> <ul> <li>The \"establish connection\" protocol enables two agents to establish a connection through a series of messages - an invitation, a connection request and a connection response.</li> <li>The \"issue credential\" protocol enables an agent to issue a credential to another agent.</li> <li>The \"present proof\" protocol enables an agent to request and receive a proof from another agent.</li> </ul> <p>Each protocol has a specification that defines the protocol's messages, one or more roles for the different participants, and a state machine that defines the state transitions triggered by the messages. For example, in the connection protocol, the messages are \"invitation\", \"connectionRequest\" and \"connectionResponse\", the roles are \"inviter\" and \"invitee\", and the states are \"invited\", \"requested\" and \"connected\". Each participant in an instance of a protocol tracks the state based on the messages they've seen.</p> <p>Code for protocols are implemented as externalized modules from the core agent code so that they can be included (or not) in an agent deployment. The protocol code must include the definition of a state object for the protocol, handlers for the protocol messages, and the events and administrative messages that are available to the controller to inject business logic into the running of the protocol. Each administrative message becomes part of the REST API exposed by the agent instance.</p> <p>Developers building Aries agents for a particular use case will generally focus on building controllers. They must understand the protocols that they are going to need, including the events the controller will receive, and the protocol's administrative messages exposed via the REST API. From time to time, such Aries agent developers might need to implement their own protocols.</p> <p>Back to the Aries Developer - Getting Started Guide. </p>"},{"location":"gettingStarted/AriesRoutingExample/","title":"Aries Routing - an example","text":"<p>In this example, we'll walk through an example of complex routing in Aries, outlining some of the possibilities that can be implemented.</p> <p>We'll start with the Alice and Bob example from the Cross Domain Messaging Aries RFC.</p> <p></p> <p>What are the DIDs involved, what's in their DIDDocs, and what communications are happening between the agents as the connections are made?</p>"},{"location":"gettingStarted/AriesRoutingExample/#the-scenario","title":"The Scenario","text":"<p>Bob and Alice want to establish a connection so that they can communicate. Bob uses an Agency endpoint (<code>https://agents-r-us.ca</code>), labelled as 9 and will have an agent used for routing, labelled as 3. We'll also focus on Bob's messages from his main iPhone, labelled as 4.  We'll ignore Bob's other agents (5 and 6) and we won't worry about Alice's configuration (agents 1, 2 and 8). While the process below is all about Bob, Alice and her agents are doing the same interactions within her domain.</p>"},{"location":"gettingStarted/AriesRoutingExample/#all-the-dids","title":"All the DIDs","text":"<p>A DID and DIDDoc are generated by each participant in each relationship. For Bob's agents (iPhone and Routing), that includes:</p> <ul> <li>Bob and Alice</li> <li>Bob and his Routing Agent</li> <li>Bob and Agency</li> <li>Bob's Routing Agent and Agency</li> </ul> <p>That's a lot more than just the Bob and Alice relationship we usually think about!</p>"},{"location":"gettingStarted/AriesRoutingExample/#diddoc-data","title":"DIDDoc Data","text":"<p>From a routing perspective the important information in the DIDDoc is the following (as defined in the DIDDoc Conventions Aries RFC):</p> <ul> <li>The public keys for agents referenced in the routing</li> <li>The <code>services</code> of type <code>did-communication</code>, including:</li> <li>the one <code>serviceEndpoint</code></li> <li>the <code>recipientKeys</code> array of referenced keys for the ultimate target(s) of the message</li> <li>the <code>routingKeys</code> array of referenced keys for the mediators</li> </ul> <p>Let's look at the <code>did-communication</code> service data in the DIDDocs generated by Bob's iPhone and Routing agents, listed above:</p> <ul> <li>Bob and Alice:</li> <li> <p>The <code>serviceEndpoint</code> that Bob tells Alice about is the endpoint for the Agency.</p> <ul> <li>We'll use for the endpoint the Agency's public DID. That way the Agency can change rotate the keys for the endpoint without all of its clients from having to update every DIDDoc with the new key.</li> </ul> </li> <li> <p>The <code>recipientKeys</code> entry is a key reference for Bob's iPhone specifically for Alice.</p> </li> <li> <p>The <code>routingKeys</code> entries is a reference to the public key for the Routing Agent.</p> </li> <li> <p>Bob and his Routing Agent:</p> </li> <li>The <code>serviceEndpoint</code> is empty because Bob's iPhone has no endpoint. See the note below for more on this.</li> <li>The <code>recipientKeys</code> entry is a key reference for Bob's iPhone specifically for the Routing Agent.</li> <li> <p>The <code>routingKeys</code> array is empty.</p> </li> <li> <p>Bob and Agency:</p> </li> <li>The <code>serviceEndpoint</code> is the endpoint for Bob's Routing Agent.</li> <li>The <code>recipientKeys</code> entry is a key reference for Bob's iPhone specifically for the Agency.</li> <li> <p>The <code>routingKeys</code> is a single entry for the key reference for the Routing Agent key.</p> </li> <li> <p>Bob's Routing Agent and Agency:</p> </li> <li>The <code>serviceEndpoint</code> is the endpoint for Bob's Routing Agent.</li> <li>The <code>recipientKeys</code> entry is a key reference for Bob's Routing Agent specifically for the Agency.</li> <li>The <code>routingKeys</code> array is empty.</li> </ul> <p>The null <code>serviceEndpoint</code> for Bob's iPhone is worth a comment. Mobile apps work by sending requests to servers, but cannot be accessed directly from a server. A DIDComm mechanism (Transports Return Route) enables a server to send messages to a Mobile agent by putting the messages into the response to a request from the mobile agent. While not formalized in an Aries RFC (yet), cloud agents can use mobile platforms' (Apple and Google) notification mechanisms to trigger a user interface event.</p>"},{"location":"gettingStarted/AriesRoutingExample/#preparing-bobs-diddoc-for-alice","title":"Preparing Bob's DIDDoc for Alice","text":"<p>Given that background, let's go through the sequence of events and messages that occur in building a DIDDoc for Bob's edge agent to send to Alice's edge agent. We'll start the sequence with all of the Agents in place as the bootstrapping of the Agency, Routing Agent and Bob's iPhone is trickier than we need to go through here. We'll call that an \"exercise left for the reader\".</p> <p>We'll start the process with Alice sending an out of band connection invitation message to Bob, e.g. through a QR code or a link in an email. Here's one possible sequence for creating the DIDDoc. Note that there are other ways this could be done:</p> <ul> <li>Bob's iPhone agent generates a new DID for Alice and prepares, and partially completes, a DIDDoc</li> <li>Bob messages the Routing Agent to send the newly created DID and to get a new public key for the Alice relationship.</li> <li>The Routing Agent records the DID for Alice and the keypair to be used for messages from Alice.</li> <li>The Routing Agent sends the DID to the Agency to let the Agency know that messages for the new DID are to go to the Routing Agent.</li> <li>The Routing Agent sends the data to Bob's iPhone agent.</li> <li>Bob's iPhone agent fills in the rest of the DIDDoc:</li> <li>the public key for the Routing Agent for the Alice relationship</li> <li>the <code>did-communication</code> service endpoint is set to the Agency public DID and</li> <li>the routing keys array with the values of the Agency public DID key reference and the Routing Agent key reference</li> </ul> <p>Note: Instead of using the DID Bob created, the Agency and Routing Agent might use the public key used to encrypt the messages for their internal routing table look up for where to send a message. In that case, the Bob and the Routing Agent share the public key instead of the DID to their respective upstream routers.</p> <p>With the DIDDoc ready, Bob uses the path provided in the invitation to send a <code>connection-request</code> message to Alice with the new DID and DIDDoc. Alice now knows how to get any DIDComm message to Bob in a secure, end-to-end encrypted manner. Subsequently, when Alice sends messages to Bob's agent, she uses the information in the DIDDoc to securely send the message to the Agency endpoint, it is sent through to the Routing Agent and on to Bob's iPhone agent for processing. Now Bob has the information he needs to securely send any DIDComm message to Alice in a secure, end-to-end encrypted manner.</p> <p>At this time, there are not specific DIDComm protocols for the \"set up the routing\" messages between the agents in Bob's domain (Agency, Routing and iPhone). Those could be implemented to be proprietary by each agent provider (since it's possible one vendor would write the code for each of those agents), but it's likely those will be specified as open standard DIDComm protocols.</p> <p>Based on the DIDDoc that Bob has sent Alice, for her to send a DIDComm message to Bob, Alice must:</p> <ul> <li>Prepare the message for Bob's Agent.</li> <li>Encrypt and place that message into a \"Forward\" message for Bob's Routing Agent.</li> <li>Encrypt and send the \"Forward\" message to Bob's Agency endpoint.</li> </ul>"},{"location":"gettingStarted/ConnectIndyNetwork/","title":"Connecting to an Indy Network","text":"<p>To be completed.</p>"},{"location":"gettingStarted/CredentialRevocation/","title":"Credential Revocation in ACA-Py","text":""},{"location":"gettingStarted/CredentialRevocation/#overview","title":"Overview","text":"<p>Revocation is perhaps the most difficult aspect of verifiable credentials to manage. This is true in AnonCreds, particularly in the management of AnonCreds revocation registries (RevRegs). Through experience in deploying use cases with ACA-Py we have found that it is very difficult for the controller (the application code) to manage revocation registries, and as such, we have changed the implementation in ACA-Py to ensure that it is handling almost all the work in revoking credentials. The only thing the controller writer has to do is track the minimum things necessary to the business rules around revocation, such as whose credentials should be revoked, and how close to real-time should revocations be published?</p> <p>Here is a  summary of all of the AnonCreds revocation activities performed by issuers. After this, we'll provide a (much shorter) list of what an ACA-Py issuer controller has to do. For those interested, there is a more complete overview of AnonCreds revocation, including all of the roles, and some details of the cryptography behind the approach:</p> <ul> <li>Issuers indicate that a credential will support revocation when creating the   credential definition (CredDef).</li> <li>Issuers create a Revocation Registry definition object of a given size   (MaxSize -- the number of credentials that can use the RevReg) and publish it   to the ledger (or more precisely, the verifiable data registry). In doing   that, a Tails file is also created and published somewhere on the Internet,   accessible to all Holders.</li> <li>Issuers create and publish an initial Revocation Registry Entry that defines   the state of all credentials within the RevReg, either all active or all   revoked. It's a really bad idea to create a RevReg starting with \"all   revoked\", so don't do that.</li> <li>Issuers issue credentials and note the \"revocation ID\" of each credential. The   \"revocation Id\" is a compound key consisting of the RevRegId from which the   credential was issued, and the index within that registry of that credential.   An index (from 1 to Max Size of the registry -- or perhaps 0 to Max Size - 1)   can only be associated with one issued credential.</li> <li>At some point, a RevReg is all used up (full), and the Issuer must create another   one. Ideally, this does not cause an extra delay in the process of issuing credentials.</li> <li>At some point, the Issuer revokes the credential of a holder, using the   revocation Id of the relevant credential.</li> <li>At some point, either in conjunction with each revocation, or for a batch of   revocations, the Issuer publishes the RevReg(s) associated with a CredDef to   the ledger. If there are multiple revocations spread across multiple RevRegs,   there may be multiple writes to the ledger.</li> </ul> <p>Since managing RevRegs is really hard for an ACA-Py controller, we have tried to minimize what an ACA-Py Issuer controller has to do, leaving everything else to be handled by ACA-Py. Of the items in the previous list, here is what an ACA-Py issuer controller does:</p> <ul> <li>Issuers flag that revocation will be used when creating the CredDef and the   desired size of the RevReg. ACA-Py takes case of creating the initial   RevReg(s) without further action by the controller.</li> <li>Two RevRegs are initially created, so there is no delay when one fills up,     and another is needed. In ongoing operations, when one RevReg fills up, the     other active RevReg is used, and a new RevReg is created.</li> <li>On creation of each RevReg, its corresponding tails file is published by     ACA-Py.</li> <li>On Issuance, the controller receives the logical \u201crevocation ID\" (combination   of RevRegId+Index) of the issued credential to track.</li> <li>On Revocation, the controller passes in the logical \u201crevocation ID\" of the   credential to be revoked, including a \u201cnotify holder\u201d flag. ACA-Py records the   revocation as pending and, if asked, sends a notification to the holder using   a DIDComm message (Aries RFC 0183: Revocation Notification).</li> <li>The Issuer requests that the revocations for a CredDefId be published. ACA-Py   figures out what RevRegs contain pending revocation and so need to be   published, and publishes each.</li> </ul> <p>That is the minimum amount of tracking the controller must do while still being able to execute the business rules around revoking credentials.</p> <p>From experience, we\u2019ve added to two extra features to deal with unexpected conditions:</p> <ul> <li>When using an Indy (or similar) ledger, if the local copy of a RevReg gets out   of sync with the ledger copy (perhaps due to a failed ledger write), the   Framework can create an update transaction to \u201cfix\u201d the issue. This is needed   for a revocation state using deltas-type solution (like Indy), but not for a   ledger that publishes revocation states containing the entire state of each   credential.</li> <li>From time to time there may be a need to \u201crotate\u201d a   RevReg \u2014 to mark existing, active RevRegs as   \u201cdecommissioned\u201d, and create new ones in their place. We\u2019ve added an endpoint   (api call) for that.</li> </ul>"},{"location":"gettingStarted/CredentialRevocation/#using-aca-py-revocation","title":"Using ACA-Py Revocation","text":"<p>The following are the ACA-Py steps and APIs involved in handling credential revocation.</p> <p>To try these out, use the ACA-Py Alice/Faber demo with tails server support enabled. You will need to have the URL of an running instance of https://github.com/bcgov/indy-tails-server.</p> <p>Include the command line parameter <code>--tails-server-base-url &lt;indy-tails-server url&gt;</code></p> <ol> <li> <p>Publish credential definition</p> <p>Credential definition is created. All required revocation collateral is also created and managed including revocation registry definition, entry, and tails file.</p> <pre><code>POST /credential-definitions\n{\n  \"schema_id\": schema_id,\n  \"support_revocation\": true,\n  # Only needed if support_revocation is true. Defaults to 100\n  \"revocation_registry_size\": size_int,\n  \"tag\": cred_def_tag # Optional\n\n}\nResponse:\n{\n  \"credential_definition_id\": \"credential_definition_id\"\n}\n</code></pre> </li> <li> <p>Issue credential</p> <p>This endpoint manages revocation data. If new revocation registry data is required, it is automatically managed in the background.</p> <pre><code>POST /issue-credential/send-offer\n{\n    \"cred_def_id\": credential_definition_id,\n    \"revoc_reg_id\": revocation_registry_id\n    \"auto_remove\": False, # We need the credential exchange record when revoking\n    ...\n}\nResponse\n{\n    \"credential_exchange_id\": credential_exchange_id\n}\n</code></pre> </li> <li> <p>Revoking credential</p> <pre><code>POST /revocation/revoke\n{\n    \"rev_reg_id\": &lt;revocation_registry_id&gt;\n    \"cred_rev_id\": &lt;credential_revocation_id&gt;,\n    \"publish\": &lt;true|false&gt;\n}\n</code></pre> <p>If publish=false, you must use <code>\u200b/issue-credential\u200b/publish-revocations</code> to publish pending revocations in batches. Revocation are not written to ledger until this is called.</p> </li> <li> <p>When asking for proof, specify the time span when the credential is NOT revoked</p> <pre><code> POST /present-proof/send-request\n {\n   \"connection_id\": ...,\n   \"proof_request\": {\n     \"requested_attributes\": [\n       {\n         \"name\": ...\n         \"restrictions\": ...,\n         ...\n         \"non_revoked\": # Optional, override the global one when specified\n         {\n           \"from\": &lt;seconds from Unix Epoch&gt; # Optional, default is 0\n           \"to\": &lt;seconds from Unix Epoch&gt;\n         }\n       },\n       ...\n     ],\n     \"requested_predicates\": [\n       {\n         \"name\": ...\n         ...\n         \"non_revoked\": # Optional, override the global one when specified\n         {\n           \"from\": &lt;seconds from Unix Epoch&gt; # Optional, default is 0\n           \"to\": &lt;seconds from Unix Epoch&gt;\n         }\n       },\n       ...\n     ],\n     \"non_revoked\": # Optional, only check revocation if specified\n     {\n       \"from\": &lt;seconds from Unix Epoch&gt; # Optional, default is 0\n       \"to\": &lt;seconds from Unix Epoch&gt;\n     }\n   }\n }\n</code></pre> </li> </ol>"},{"location":"gettingStarted/CredentialRevocation/#revocation-notification","title":"Revocation Notification","text":"<p>ACA-Py supports Revocation Notification v1.0.</p> <p>Note: The optional <code>~please_ack</code> is not currently supported.</p>"},{"location":"gettingStarted/CredentialRevocation/#issuer-role","title":"Issuer Role","text":"<p>To notify connections to which credentials have been issued, during step 2 above, include the following attributes in the request body:</p> <ul> <li><code>notify</code> - A boolean value indicating whether or not a notification should be   sent. If the argument <code>--notify-revocation</code> is used on startup, this value   defaults to <code>true</code>. Otherwise, it will default to <code>false</code>. This value   overrides the <code>--notify-revocation</code> flag; the value of <code>notify</code> always takes   precedence.</li> <li><code>connection_id</code> - Connection ID for the connection of the credential holder.   This is required when <code>notify</code> is <code>true</code>.</li> <li><code>thread_id</code> - Message Thread ID of the credential exchange message that   resulted in the credential now being revoked. This is required when <code>notify</code>   is <code>true</code></li> <li><code>comment</code> - An optional comment presented to the credential holder as part of   the revocation notification. This field might contain the reason for   revocation or some other human readable information about the revocation.</li> </ul> <p>Your request might look something like:</p> <pre><code>POST /revocation/revoke\n{\n    \"rev_reg_id\": &lt;revocation_registry_id&gt;\n    \"cred_rev_id\": &lt;credential_revocation_id&gt;,\n    \"publish\": &lt;true|false&gt;,\n    \"notify\": true,\n    \"connection_id\": &lt;connection id&gt;,\n    \"thread_id\": &lt;thread id&gt;,\n    \"comment\": \"optional comment\"\n}\n</code></pre>"},{"location":"gettingStarted/CredentialRevocation/#holder-role","title":"Holder Role","text":"<p>On receipt of a revocation notification, an event with topic <code>acapy::revocation-notification::received</code> and payload containing the thread ID and comment is emitted on the event bus. This can be handled in plugins to further customize notification handling.</p> <p>If the argument <code>--monitor-revocation-notification</code> is used on startup, a webhook with the topic <code>revocation-notification</code> and a payload containing the thread ID and comment is emitted to registered webhook urls.</p>"},{"location":"gettingStarted/CredentialRevocation/#manually-creating-revocation-registries","title":"Manually Creating Revocation Registries","text":"<p>NOTE: This capability is deprecated and will likely be removed entirely in an upcoming release of ACA-Py.</p> <p>The process for creating revocation registries is completely automated - when you create a Credential Definition with revocation enabled, a revocation registry is automatically created (in fact 2 registries are created), and when a registry fills up, a new one is automatically created.</p> <p>However the ACA-Py admin api supports endpoints to explicitly create a new revocation registry, if you desire.</p> <p>There are several endpoints that must be called, and they must be called in this order:</p> <ol> <li> <p>Create revoc registry <code>POST /revocation/create-registry</code></p> </li> <li> <p>you need to provide the credential definition id and the size of the registry</p> </li> <li> <p>Fix the tails file URI <code>PATCH /revocation/registry/{rev_reg_id}</code></p> </li> <li> <p>here you need to provide the full URI that will be written to the ledger, for example:</p> </li> </ol> <pre><code>{\n  \"tails_public_uri\": \"http://host.docker.internal:6543/VDKEEMMSRTEqK4m7iiq5ZL:4:VDKEEMMSRTEqK4m7iiq5ZL:3:CL:8:faber.agent.degree_schema:CL_ACCUM:3cb5c439-928c-483c-a9a8-629c307e6b2d\"\n}\n</code></pre> <ol> <li> <p>Post the revoc def to the ledger <code>POST /revocation/registry/{rev_reg_id}/definition</code></p> </li> <li> <p>if you are an author (i.e. have a DID with restricted ledger write access) then this transaction may need to go through an endorser</p> </li> <li> <p>Write the tails file <code>PUT /revocation/registry/{rev_reg_id}/tails-file</code></p> </li> <li> <p>the tails server will check that the registry definition is already written to the ledger</p> </li> <li> <p>Post the initial accumulator value to the ledger <code>POST /revocation/registry/{rev_reg_id}/entry</code></p> </li> <li> <p>if you are an author (i.e. have a DID with restricted ledger write access) then this transaction may need to go through an endorser</p> </li> <li>this operation MUST be performed on the the new revoc registry def BEFORE any revocation operations are performed</li> </ol>"},{"location":"gettingStarted/CredentialRevocation/#revocation-registry-rotation","title":"Revocation Registry Rotation","text":"<p>From time to time an Issuer may want to issue credentials from a new Revocation Registry. That can be done by changing the Credential Definition, but that could impact verifiers. Revocation Registries go through a series of state changes: <code>init</code>, <code>generated</code>, <code>posted</code>, <code>active</code>, <code>full</code>, <code>decommissioned</code>. When issuing revocable credentials, the work is done with the <code>active</code> registry record. There are always 2 <code>active</code> registry records: one for tracking revocation until it is full, and the second to act as a \"hot swap\" in case issuance is done when the primary is full and being replaced. This ensures that there is always an <code>active</code> registry. When rotating, all registry records (except records in <code>init</code> state) are <code>decommissioned</code> and a new pair of <code>active</code> registry records are created.</p> <p>Issuers can rotate their Credential Definition Revocation Registry records with a simple call: <code>POST /revocation/active-registry/{cred_def_id}/rotate</code></p> <p>It is advised that Issuers ensure the active registry is ready by calling <code>GET /revocation/active-registry/{cred_def_id}</code> after rotation and before issuance (if possible).</p>"},{"location":"gettingStarted/DIDcommMsgs/","title":"Deeper Dive: DIDComm Messaging","text":"<p>DIDComm peer-to-peer messages are asynchronous messages that one agent sends to another - for example, Faber would send to Alice. In between, there may be other agents and message processing, but at the edges, Faber appears to be messaging directly with Alice using encryption based on the DIDs and DIDDocs that the two shared when establishing a connection. The messages are JSON-LD-friendly messages with a \"type\" that defines the namespace, protocol, protocol version and type of the message, an \"id\" that is GUID for the message, and additional fields as required by the message type. The namespace is currently defined to be a public DID that should be globally resolvable to a protocol specification. Currently, \"core\" messages use a DID that is not yet globally resolvable - Daniel Hardman has the keys associated with the DID.</p> <p>Link: Message Types</p> <p>As protocols are executed, the data associated with the protocol is stored in the (currently named) wallet of the agent. The data primarily consists of the state object for that instance of the protocol, and any artifacts of running the protocol. For example, when establishing a connection, the metadata associated with the connection (DIDs, DID Documents and private keys) is stored in the agent's wallet. Likewise, ledger data is cached in the wallet (DIDs, schema, credential definitions, etc.) and credentials. This is taken care of by the Aries agent and the protocols configured into the agent.</p>"},{"location":"gettingStarted/DIDcommMsgs/#message-decorators","title":"Message Decorators","text":"<p>In addition to protocol specific data elements in messages, messages can include \"decorators\", standardized message elements that define cross-cutting behavior. The most common example is the \"thread\" decorator, which is used to link the messages in a protocol instance. As messages go back and forth between agents to complete an instance of a protocol (e.g. issuing a credential), the thread decorator data elements let the agents know to which protocol instance the message belongs. Other currently defined examples of decorators include attachments, localization, tracing and timing. Decorators are often processed by the core of the agent, but some are processed by the protocol message handlers. For example, the thread decorator processed to retrieve the protocol state object for that instance (thread) of the protocol before control is passed to the protocol message handler.</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/","title":"Decentralized Identity Use Case Demos","text":"<p>The following are some demos that you can go through to see verifiable credentials in action. For each of the demos, we've included some guidance on what you should get out of the demo - and where you should stop exploring the demos. Later on in this guide we have some command line demos built on current generation code for developers wanting to look at what's going on under the hood.</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/#bc-gov-showcase","title":"BC Gov Showcase","text":"<p>Try out the BC Gov Showcase to download a production Wallet for holding Verifiable Credentials, and then use your new wallet to get and present credentials in some sample scenarios. The end-to-end verifiable credential experience in 30 minutes or less.</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/#traction-anoncreds-workshop","title":"Traction AnonCreds Workshop","text":"<p>Now that you have a wallet, how about being an issuer, and experience what is needed on that side of an exchange? To do that, try the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/DecentralizedIdentityDemos/#more-demos-please","title":"More demos, please","text":"<p>Interested in seeing your demos/use cases added to this list? Submit an issue or a PR and we'll see about including it in this list.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/","title":"What should I work on? Options for Aries/Indy Developers","text":"<p>Now that you know the basics of the Indy/Aries eco-system, what do you want to work on? There are many projects at different levels of the eco-system you could choose to work on, and many ways to contribute to the community.</p> <p>This is an important summary for newcomers, as often the temptation is to start at a level far below where you plan to focus your attention. Too often devs coming into the community start at \"the blockchain\"; at <code>indy-node</code> (the Indy public ledger) or the <code>indy-sdk</code>. That is far below where the majority of developers will work and is not really that helpful if what you really want to do is build decentralized identity applications.</p> <p>In the following, we go through the layers from the top of the stack to the bottom. Our expectation is that the majority of developers will work at the application level, and there will be fewer contributing developers each layer down you go. This is not to dissuade anyone from contributing at the lower levels, but rather to say if you are not going to contribute at the lower levels, you don't need to everything about it. It's much like web development - you don't need to know TCP/IP to build web apps.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#building-decentralized-identity-applications","title":"Building Decentralized Identity Applications","text":"<p>If you just want to build enterprise applications on top of the decentralized identity-related Hyperledger projects, you can start with building cloud-based controller apps using any language you want, and deploying your code with an instance of the code in this repository (aries-cloudagent-python).</p> <p>If you want to build a mobile agent, there are open source options available, including Aries-MobileAgent-Xamarin (aka \"Aries MAX\"), which is built on Aries Framework .NET, and Aries Mobile Agent React Native, which is built on Aries Framework JavaScript.</p> <p>As a developer building applications that use/embed Aries agents, you should join the Aries Working Group's weekly calls and watch the aries-rfcs repo to see what protocols are being added and extended. In some cases, you may need to create your own protocols to be added to this repository, and if you are looking for interoperability, you should specify those protocols in an open way, involving the community.</p> <p>Note that if building apps is what you want to do, you don't need to do a deep dive into the Aries SDK, the Indy SDK or the Indy Node public ledger. You need to know the concepts, but it's not a requirement that know the code base intimately.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#contributing-to-aries-cloudagent-python","title":"Contributing to <code>aries-cloudagent-python</code>","text":"<p>Of course as you build applications using <code>aries-cloudagent-python</code>, you will no doubt find deficiencies in the code and features you want added. Contributions to this repo will always be welcome.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#supporting-additional-ledgers","title":"Supporting Additional Ledgers","text":"<p><code>aries-cloudagent-python</code> currently supports only Hyperledger Indy-based public ledgers and verifiable credentials exchange. A goal of Hyperledger Aries is to be ledger-agnostic, and to support other ledgers. We're experimenting with adding support for other ledgers, and would welcome assistance in doing that.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#other-agent-frameworks","title":"Other Agent Frameworks","text":"<p>Although controllers for an <code>aries-cloudagent-python</code> instance can be written in any language, there is definitely a place for functionality equivalent (and better) to what is in this repo in other languages. Use the example provided by the <code>aries-cloudagent-python</code>, evolve that using a different language, and as you discover better ways to do things, discuss and share those improvements in the broader Aries community so that this and other codebases improve.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#improving-aries-sdk","title":"Improving Aries SDK","text":"<p>This code base and other Aries agent implementations currently embed the <code>indy-sdk</code>. However, much of the code in the <code>indy-sdk</code> is being migrated into a variety of Aries language specific repositories. How this migration is to be done is still being decided, but it makes sense that the agent-type things be moved to Aries repositories. A number of language specific Aries SDK repos have been created and are being populated.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#improving-the-indy-sdk","title":"Improving the Indy SDK","text":"<p>Dropping down a level from Aries and into Indy, the indy-sdk needs to continue to evolve. The code base is robust, of high quality and well thought out, but it needs to continue to add new capabilities and improve existing features. The <code>indy-sdk</code> is implemented in Rust, to produce a C-callable library that can be used by client libraries built in a variety of languages.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#improving-indy-node","title":"Improving Indy Node","text":"<p>If you are interested in getting into the public ledger part of Indy, particularly if you are going to be a Sovrin Steward, you should take a deep look into indy-node. Like the <code>indy-sdk</code>, <code>indy-node</code> is robust, of high quality and is well thought out. As the network grows, use cases change and new cryptographic primitives move into the mainstream, <code>indy-node</code> capabilities will need to evolve. <code>indy-node</code> is coded in Python.</p>"},{"location":"gettingStarted/IndyAriesDevOptions/#working-in-cryptography","title":"Working in Cryptography","text":"<p>Finally, at the deepest level, and core to all of the projects is the cryptography in Hyperledger Ursa. If you are a cryptographer, that's where you want to be - and we want you there.</p>"},{"location":"gettingStarted/IndyBasics/","title":"Indy, Verifiable Credentials and Decentralized Identity Basics","text":"<p>NOTE: If you are developer building apps on top of Aries and Indy, you DO NOT need to know the nuts and bolts of Indy to build applications. You need to know about verifiable credentials and the concepts of self-sovereign identity. But as an app developer, you don't need to do the Indy getting started pieces. Aries takes care of those details for you. The introduction linked here should be sufficient.</p> <p>If you are new to Indy and verifiable credentials and want to learn the core concepts, this link provides a solid foundation into the goals and purpose of Indy including verifiable credentials, DIDs, decentralized/self-sovereign identity, the Sovrin Foundation and more. The document is the content of the Indy chapter of the Hyperledger edX Blockchain for Business course (which you could also go through).</p> <p>Feel free to do the demo that is referenced in the material, but we recommend that you not dig into that codebase. It's pretty old now - almost a year!  We've got much more relevant examples later in this guide.</p> <p>As well, don't use the guidance in the course to dive into the content about \"Getting Started\" with Indy. Come back here as this content is far more relevant to the current state of Indy and Aries.</p>"},{"location":"gettingStarted/IndyBasics/#tldr","title":"tl;dr","text":"<p>Indy provides an implementation of the basic functions required to implement a network for self-sovereign identity (SSI) - a ledger, client SDKs for interacting with the ledger, DIDs, and capabilities for issuing, holding and proving verifiable credentials.</p> <p>Back to the Aries Developer - Getting Started Guide.</p>"},{"location":"gettingStarted/IssuingAnonCredsCredentials/","title":"Issuing AnonCreds Credentials","text":"<p>Become an issuer, and define, publish and issue verifiable credentials to a mobile wallet. Run the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/PresentingAnonCredsProofs/","title":"Presenting AnonCreds Proofs","text":"<p>Become a verifier, and construct a presentation request, send the request to a mobile wallet, get a presentation derived from AnonCreds verifiable credentials and verify the presentation. Run the Traction AnonCreds Workshop. Get your own (temporary -- it will be gone in a few weeks!) Aries Cloud Agent Python-based issuer/verifier agent. Connect to the wallet on your mobile phone, issue a credential and then present it back. Lots to learn, without ever leaving your browser!</p>"},{"location":"gettingStarted/RoutingEncryption/","title":"Deeper Dive: DIDComm Message Routing and Encryption","text":"<p>Many Aries edge agents do not directly receive messages from a peer edge agent - they have agents in between that route messages to them. This is done for many reasons, such as:</p> <ul> <li>The agent is on a mobile device that does not have a persistent connection and so uses a cloud agent.</li> <li>The person does not want to allow correlation of their agent across relationships and so they use a shared, common endpoint (e.g. <code>https://agents-R-Us.ca</code>) that they are \"hidden in a crowd\".</li> <li>An enterprise wants a single gateway to the many enterprise agents they have in their organization.</li> </ul> <p>Thus, when a DIDComm message is sent from one edge agent to another, it is routed per the instructions of the receiver and for the needs of the sender. For example, in the following picture, Alice might be told by Bob to send messages to his phone (agent 4) via agents 9 and 3, and Alice might always send out messages via agent 2.</p> <p></p> <p>The following looks at how those requirements are met with mediators (for example, agents 9 and 3) and relays (agent 2).</p>"},{"location":"gettingStarted/RoutingEncryption/#inbound-routing-mediators","title":"Inbound Routing - Mediators","text":"<p>To tell a sender how to get a message to it, an agent puts into the DIDDoc for that sender a service endpoint for the recipient (with an encryption key) and an ordered list (possibly empty) of routing keys (called \"mediators\") to use when sending the message. To send the message, the sender must:</p> <ul> <li>Prepare the message to be sent to the recipient</li> <li>Successively encrypt and wrap the message for each intermediate mediator in a \"forward\" message - an envelope.</li> <li>Encrypt and send the message to the first agent in the routing</li> </ul> <p>Note that when an agent uses mediators, it is there responsibility to notify any mediators that need to know of the new relationship that has been formed using the connection protocol and the routing needs of that relationship - where to send messages that arrive destined for a given verkey. Mediator agents have what amounts to a routing table to know when they receive a forward message for a given verkey, where it should go.</p> <p>Link: DIDDoc conventions for inbound routing</p>"},{"location":"gettingStarted/RoutingEncryption/#relays","title":"Relays","text":"<p>Inbound routing described above covers mediators for the receiver that the sender must know about. In addition, either the sender or the receiver may also have relays they use for outbound messages. Relays are routing agents not known to other parties, but that participate in message routing. For example, an enterprise agent might send all outbound traffic to a single gateway in the organization. When sending to a relay, the sender just wraps the message in another \"forward\" message envelope.</p> <p>Link: Mediators and Relays</p>"},{"location":"gettingStarted/RoutingEncryption/#message-encryption","title":"Message Encryption","text":"<p>The DIDComm encryption handling is handling within the Aries agent, and not really something a developer building applications using an agent needs to worry about. Further, within an Aries agent, the handling of the encryption is left to libraries to handle - ultimately calling dependencies from Hyperledger Ursa. To encrypt a message, the agent code calls a <code>pack()</code> function to handle the encryption, and to decrypt a message, the agent code calls a corresponding <code>unpack()</code> function. The \"wire messages\" (as originally called) are described in detail here, including variations for sender authenticated and anonymous encrypting. Wire messages were meant to indicate the handling of a message from one agent directly to another, versus the higher level concept of routing a message from an edge agent to a peer edge agent.</p> <p>Much thought has also gone into repudiable and non-repudiable messaging, as described here.</p>"},{"location":"gettingStarted/YourOwnAriesAgent/","title":"Creating Your Own Aries Agent","text":"<p>Use the \"next steps\" in the Traction AnonCreds Workshop and create your own controller. The Aries ACA-Py Controllers repository has some samples to get you started.</p>"},{"location":"testing/AgentTracing/","title":"Using Tracing in ACA-PY","text":"<p>The aca-py agent supports message tracing, according to the Tracing RFC.</p> <p>Tracing can be enabled globally, for all messages/events, or it can be enabled on an exchange-by-exchange basis.</p> <p>Tracing is configured globally for the agent.</p>"},{"location":"testing/AgentTracing/#aca-py-configuration","title":"ACA-PY Configuration","text":"<p>The following options can be specified when starting the aca-py agent:</p> <pre><code>  --trace               Generate tracing events.\n  --trace-target &lt;trace-target&gt;\n                        Target for trace events (\"log\", \"message\", or http\n                        endpoint).\n  --trace-tag &lt;trace-tag&gt;\n                        Tag to be included when logging events.\n  --trace-label &lt;trace-label&gt;\n                        Label (agent name) used logging events.\n</code></pre> <p>The <code>--trace</code> option enables tracing globally for the agent, the other options can configure the trace destination and content (default is <code>log</code>).</p> <p>Tracing can be enabled on an exchange-by-exchange basis, by including <code>{ ... \"trace\": True, ...}</code> in the JSON payload to the API call (for credential and proof exchanges).</p>"},{"location":"testing/AgentTracing/#enabling-tracing-in-the-alicefaber-demo","title":"Enabling Tracing in the Alice/Faber Demo","text":"<p>The <code>run_demo</code> script supports the following parameters and environment variables.</p> <p>Environment variables:</p> <pre><code>TRACE_ENABLED          Flag to enable tracing\n\nTRACE_TARGET_URL       Host:port of endpoint to log trace events (e.g. logstash:9700)\n\nDOCKER_NET             Docker network to join (must be used if ELK stack is running in docker)\n\nTRACE_TAG              Tag to be included in all logged trace events\n</code></pre> <p>Parameters:</p> <pre><code>--trace-log            Enables tracing to the standard log output\n                       (sets TRACE_ENABLED, TRACE_TARGET, TRACE_TAG)\n\n--trace-http           Enables tracing to an HTTP endpoint (specified by TRACE_TARGET_URL)\n                       (sets TRACE_ENABLED, TRACE_TARGET, TRACE_TAG)\n</code></pre> <p>When running the Faber controller, tracing can be enabled using the <code>T</code> menu option:</p> <pre><code>Faber      | Connected\n    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n[1/2/3/T/X] t\n\n&gt;&gt;&gt; Credential/Proof Exchange Tracing is ON\n    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n\n[1/2/3/T/X] t\n\n&gt;&gt;&gt; Credential/Proof Exchange Tracing is OFF\n    (1) Issue Credential\n    (2) Send Proof Request\n    (3) Send Message\n    (T) Toggle tracing on credential/proof exchange\n    (X) Exit?\n\n[1/2/3/T/X]\n</code></pre> <p>When <code>Exchange Tracing</code> is <code>ON</code>, all exchanges will include tracing.</p>"},{"location":"testing/AgentTracing/#logging-trace-events-to-an-elk-stack","title":"Logging Trace Events to an ELK Stack","text":"<p>You can use the <code>ELK</code> stack in the ELK Stack sub-directory as a target for trace events, just start the ELK stack using the docker-compose file and then in two separate bash shells, startup the demo as follows:</p> <pre><code>DOCKER_NET=elknet TRACE_TARGET_URL=logstash:9700 ./run_demo faber --trace-http\n</code></pre> <pre><code>DOCKER_NET=elknet TRACE_TARGET_URL=logstash:9700 ./run_demo alice --trace-http\n</code></pre>"},{"location":"testing/AgentTracing/#hooking-into-event-messaging","title":"Hooking into event messaging","text":"<p>ACA-PY supports sending events to web hooks, which allows the demo agents to display them in the CLI. To also send them to another end point, use the <code>--webhook-url</code> option, which requires the <code>WEBHOOK_URL</code> environment variable. Configure an end point running on the docker host system, port 8888, use the following:</p> <pre><code>WEBHOOK_URL=host.docker.internal:8888 ./run_demo faber --webhook-url\n</code></pre>"},{"location":"testing/INTEGRATION-TESTS/","title":"Integration Tests for Aca-py using Behave","text":"<p>Integration tests for aca-py are implemented using Behave functional tests to drive aca-py agents based on the alice/faber demo framework.</p> <p>If you are new to the ACA-Py integration test suite, this video from ACA-Py Maintainer @ianco describes the Integration Tests in ACA-Py, how to run them and how to add more tests. See also the video at the end of this document about running Aries Agent Test Harness tests before you submit your pull requests.</p>"},{"location":"testing/INTEGRATION-TESTS/#getting-started","title":"Getting Started","text":"<p>To run the aca-py Behave tests, open a bash shell run the following:</p> <pre><code>git clone https://github.com/bcgov/von-network\ncd von-network\n./manage build\n./manage start\ncd ..\ngit clone https://github.com/bcgov/indy-tails-server.git\ncd indy-tails-server/docker\n./manage build\n./manage start\ncd ../..\ngit clone https://github.com/hyperledger/aries-cloudagent-python\ncd aries-cloudagent-python/demo\n./run_bdd -t ~@taa_required\n</code></pre> <p>Note that an Indy ledger and tails server are both required (these can also be specified using environment variables).</p> <p>Note also that some tests require a ledger with TAA enabled, how to run these tests will be described later.</p> <p>By default the test suite runs using a default (SQLite) wallet, to run the tests using postgres run the following:</p> <pre><code># run the above commands, up to cd aries-cloudagent-python/demo\ndocker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres:10\nACAPY_ARG_FILE=postgres-indy-args.yml ./run_bdd\n</code></pre> <p>To run the tests against the back-end <code>askar</code> libraries (as opposed to indy-sdk) run the following:</p> <pre><code>BDD_EXTRA_AGENT_ARGS=\"{\\\"wallet-type\\\":\\\"askar\\\"}\" ./run_bdd -t ~@taa_required\n</code></pre> <p>(Note that <code>wallet-type</code> is currently the only extra argument supported.)</p> <p>You can run individual tests by specifying the tag(s):</p> <pre><code>./run_bdd -t @T001-AIP10-RFC0037\n</code></pre>"},{"location":"testing/INTEGRATION-TESTS/#running-integration-tests-which-require-taa","title":"Running Integration Tests which require TAA","text":"<p>To run a local von-network with TAA enabled,run the following:</p> <pre><code>git clone https://github.com/bcgov/von-network\ncd von-network\n./manage build\n./manage start --taa-sample --logs\n</code></pre> <p>You can then run the TAA-enabled tests as follows:</p> <pre><code>./run_bdd -t @taa_required\n</code></pre> <p>or:</p> <pre><code>BDD_EXTRA_AGENT_ARGS=\"{\\\"wallet-type\\\":\\\"askar\\\"}\" ./run_bdd -t @taa_required\n</code></pre> <p>The agents run on a pre-defined set of ports, however occasionally your local system may already be using one of these ports.  (For example MacOS recently decided to use 8021 for the ftp proxy service.)</p> <p>To overriide the default port settings:</p> <pre><code>AGENT_PORT_OVERRIDE=8030 ./run_bdd -t &lt;some tags&gt;\n</code></pre> <p>(Note that since the test run multiple agents you require up to 60 available ports.)</p>"},{"location":"testing/INTEGRATION-TESTS/#aca-py-integration-tests-vs-aries-agent-test-harness-aath","title":"Aca-py Integration Tests vs Aries Agent Test Harness (AATH)","text":"<p>Aca-py Behave tests are based on the interoperability tests that are implemented in the Aries Agent Test Harness (AATH).  Both use Behave (Gherkin) to execute tests against a running aca-py agent (or in the case of AATH, against any compatible Aries agent), however the aca-py integration tests focus on aca-py specific features.</p> <p>AATH:</p> <ul> <li>Main purpose is to test interoperability between Aries agents</li> <li>Implements detailed tests based on Aries RFC's (runs different scenarios, tests exception paths, etc.)</li> <li>Runs Aries agents using Docker images (agents run for the duration of the tests)</li> <li>Uses a standard \"backchannel\" to support integration of any Aries agent</li> </ul> <p>Aca-py integration tests:</p> <ul> <li>Main purpose is to test aca-py</li> <li>Implements tests based on Aries RFC's, but not to the level of detail as AATH (runs (mostly) happy path scenarios against multiple agent configurations)</li> <li>Tests aca-py specific configurations and features</li> <li>Starts and stops agents for each tests to test different aca-py configurations</li> <li>Uses the same Python framework as used for the interactive Alice/Faber demo</li> </ul>"},{"location":"testing/INTEGRATION-TESTS/#configuration-driven-tests","title":"Configuration-driven Tests","text":"<p>Aca-py integration tests use the same configuration approach as AATH, documented here.</p> <p>In addition to support for external schemas, credential data etc, the aca-py integration tests support configuration of the aca-py agents that are used to run the test.  For example:</p> <pre><code>Scenario Outline: Present Proof where the prover does not propose a presentation of the proof and is acknowledged\n  Given \"3\" agents\n     | name  | role     | capabilities        |\n     | Acme  | issuer   | &lt;Acme_capabilities&gt; |\n     | Faber | verifier | &lt;Acme_capabilities&gt; |\n     | Bob   | prover   | &lt;Bob_capabilities&gt;  |\n  And \"&lt;issuer&gt;\" and \"Bob\" have an existing connection\n  And \"Bob\" has an issued &lt;Schema_name&gt; credential &lt;Credential_data&gt; from &lt;issuer&gt;\n  ...\n\n  Examples:\n     | issuer | Acme_capabilities        | Bob_capabilities | Schema_name    | Credential_data          | Proof_request  |\n     | Acme   | --public-did             |                  | driverslicense | Data_DL_NormalizedValues | DL_age_over_19 |\n     | Faber  | --public-did  --mediator | --mediator       | driverslicense | Data_DL_NormalizedValues | DL_age_over_19 |\n</code></pre> <p>In the above example, the test will run twice using the parameters specified in the \"Examples\" section.  The Acme, Faber and Bob agents will be started for the test and then shut down when the test is completed.</p> <p>The agent's \"capabilities\" are specified using the same command-line parameters that are supported for the Alice/Faber demo agents.</p>"},{"location":"testing/INTEGRATION-TESTS/#global-configuration-for-all-aca-py-agents-under-test","title":"Global Configuration for All Aca-py Agents Under Test","text":"<p>You can specify parameters that are applied to all aca-py agents using the <code>ACAPY_ARG_FILE</code> environment variable, for example:</p> <pre><code>ACAPY_ARG_FILE=postgres-indy-args.yml ./run_bdd\n</code></pre> <p>... will apply the parameters in the <code>postgres-indy-args.yml</code> file (which just happens to configure a postgres wallet) to all agents under test.</p> <p>Or the following:</p> <pre><code>ACAPY_ARG_FILE=askar-indy-args.yml ./run_bdd\n</code></pre> <p>... will run all the tests against an askar wallet (the new shared components, which replace indy-sdk).</p> <p>Any aca-py arguement can be included in the yml file, and order-of-precidence applies (see https://pypi.org/project/ConfigArgParse/).</p>"},{"location":"testing/INTEGRATION-TESTS/#specifying-environment-parameters-when-running-integration-tests","title":"Specifying Environment Parameters when Running Integration Tests","text":"<p>Aca-py integration tests support the following environment-driven configuration:</p> <ul> <li><code>LEDGER_URL</code> - specify the ledger url</li> <li><code>TAILS_NETWORK</code> - specify the docker network the tailer server is running on</li> <li><code>PUBLIC_TAILS_URL</code> - specify the public url of the tails server</li> <li><code>ACAPY_ARG_FILE</code> - specify global aca-py parameters (see above)</li> </ul>"},{"location":"testing/INTEGRATION-TESTS/#running-specific-test-scenarios","title":"Running specific test scenarios","text":"<p>Behave tests are tagged using the same standard tags as used in AATH.</p> <p>To run a specific set of Aca-py integration tests (or exclude specific tests):</p> <pre><code>./run_bdd -t tag1 -t ~tag2\n</code></pre> <p>(All command line parameters are passed to the <code>behave</code> command, so all parameters supported by behave can be used.)</p>"},{"location":"testing/INTEGRATION-TESTS/#aries-agent-test-harness-aca-py-tests","title":"Aries Agent Test Harness ACA-Py Tests","text":"<p>This video is a presentation by Aries Cloud Agent Python (ACA-Py) developer @ianco about using the Aries Agent Test Harness for local pre-release testing of ACA-Py. Have a big change that you want to test with other Aries Frameworks? Following this guidance to run AATH tests with your under-development branch of ACA-Py.</p>"},{"location":"testing/Logging/","title":"Logging docs","text":"<p>ACA_Py supports multiple configurations of logging.</p>"},{"location":"testing/Logging/#log-level","title":"Log level","text":"<p>ACA-Py's logging is based on python's logging lib. Log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARNING</code> are available. Other log levels fall back to <code>WARNING</code>.</p>"},{"location":"testing/Logging/#per-tenant-logging","title":"Per Tenant Logging","text":"<p>Supports writing of log messages to a file with <code>wallet_id</code> as the tenant identifier for each. To enable this, both multitenant mode (<code>--multitenant</code>) and writing to log file option (<code>--log-file</code>) are required. If both <code>--multitenant</code> and <code>--log-file</code> are not passed when starting up ACA-Py, then it will use <code>default_logging_config.ini</code> config (backward compatible) and not log at a per tenant level.</p>"},{"location":"testing/Logging/#command-line-arguments","title":"Command Line Arguments","text":"<ul> <li><code>--log-level</code> - The log level to log on std out</li> <li><code>--log-file</code> - Enables writing of logs to file. The provided value becomes path to a file to log to. If no value or empty string is provided then it will try to get the path from the config file</li> <li><code>--log-config</code> - Specifies a custom logging configuration file</li> </ul> <p>Example:</p> <pre><code>./bin/aca-py start --log-level debug --log-file acapy.log --log-config aries_cloudagent.config:default_per_tenant_logging_config.ini\n\n./bin/aca-py start --log-level debug --log-file --multitenant --log-config ./aries_cloudagent/config/default_per_tenant_logging_config.yml\n</code></pre>"},{"location":"testing/Logging/#environment-variables","title":"Environment Variables","text":"<p>The log level can be configured using the environment variable <code>ACAPY_LOG_LEVEL</code>. The log file can be set by <code>ACAPY_LOG_FILE</code>. The log config can be set by <code>ACAPY_LOG_CONFIG</code>.</p> <p>Example:</p> <pre><code>ACAPY_LOG_LEVEL=info ACAPY_LOG_FILE=./acapy.log ACAPY_LOG_CONFIG=./acapy_log.ini ./bin/aca-py start\n</code></pre>"},{"location":"testing/Logging/#acapy-config-file","title":"Acapy Config File","text":"<p>Following parameters can be used in a configuration file like this.</p> <pre><code>log-level: WARNING\ndebug-connections: false\ndebug-presentations: false\n</code></pre> <p>Warning: debug-connections and debug-presentations must not be used in a production environment as they log also credential claims values. Both parameters are independent of the log level, which means: Also if log-level is set to WARNING, connections and presentations will be logged like in debug log level.</p>"},{"location":"testing/Logging/#log-config-file","title":"Log config file","text":"<p>The path to config file is provided via <code>--log-config</code>.</p> <p>Find an example in default_logging_config.ini.</p> <p>You can find more detail description in the logging documentation.</p> <p>For per tenant logging, find an example in default_per_tenant_logging_config.ini, which sets up  <code>TimedRotatingFileMultiProcessHandler</code> and <code>StreamHandler</code> handlers. Custom <code>TimedRotatingFileMultiProcessHandler</code> handler supports the ability to cleanup logs by time and maintain backup logs and a custom JSON formatter for logs. The arguments for it such as <code>file name</code>, <code>when</code>, <code>interval</code> and <code>backupCount</code> can be passed as <code>args=('acapy.log', 'd', 7, 1,)</code> (also shown below). Note: <code>backupCount</code> of 0 will mean all backup log files will be retained and not deleted at all. More details about these attributes can be found here</p> <pre><code>[loggers]\nkeys=root\n\n[handlers]\nkeys=stream_handler, timed_file_handler\n\n[formatters]\nkeys=formatter\n\n[logger_root]\nlevel=ERROR\nhandlers=stream_handler, timed_file_handler\n\n[handler_stream_handler]\nclass=StreamHandler\nlevel=DEBUG\nformatter=formatter\nargs=(sys.stderr,)\n\n[handler_timed_file_handler]\nclass=logging.handlers.TimedRotatingFileMultiProcessHandler\nlevel=DEBUG\nformatter=formatter\nargs=('acapy.log', 'd', 7, 1,)\n\n[formatter_formatter]\nformat=%(asctime)s %(wallet_id)s %(levelname)s %(pathname)s:%(lineno)d %(message)s\n</code></pre> <p>For <code>DictConfig</code> (<code>dict</code> logging config file), find an example in default_per_tenant_logging_config.yml with same attributes as <code>default_per_tenant_logging_config.ini</code> file.</p> <pre><code>version: 1\nformatters:\n  default:\n    format: '%(asctime)s %(wallet_id)s %(levelname)s %(pathname)s:%(lineno)d %(message)s'\nhandlers:\n  console:\n    class: logging.StreamHandler\n    level: DEBUG\n    formatter: default\n    stream: ext://sys.stderr\n  rotating_file:\n    class: logging.handlers.TimedRotatingFileMultiProcessHandler\n    level: DEBUG\n    filename: 'acapy.log'\n    when: 'd'\n    interval: 7\n    backupCount: 1\n    formatter: default\nroot:\n  level: INFO\n  handlers:\n    - console\n    - rotating_file\n</code></pre>"},{"location":"testing/Troubleshooting/","title":"Troubleshooting Aries Cloud Agent Python","text":"<p>This document contains some troubleshooting information that contributors to the community think may be helpful. Most of the content here assumes the reader has gotten started with ACA-Py and has arrived here because of an issue that came up in their use of ACA-Py.</p> <p>Contributions (via pull request) to this document are welcome. Topics added here will mostly come from reported issues that contributors think would be helpful to the larger community.</p>"},{"location":"testing/Troubleshooting/#table-of-contents","title":"Table of Contents","text":"<ul> <li>Unable to Connect to Ledger</li> <li>Local ledger running?</li> <li>Any Firewalls</li> <li>Damaged, Unpublishable Revocation Registry</li> </ul>"},{"location":"testing/Troubleshooting/#unable-to-connect-to-ledger","title":"Unable to Connect to Ledger","text":"<p>The most common issue hit by first time users is getting an error on startup \"unable to connect to ledger\". Here are a list of things to check when you see that error.</p>"},{"location":"testing/Troubleshooting/#local-ledger-running","title":"Local ledger running?","text":"<p>Unless you specify via startup parameters or environment variables that you are using a public Hyperledger Indy ledger, ACA-Py assumes that you are running a local ledger -- an instance of von-network. If that is the cause -- have you started your local ledger, and did it startup properly.  Things to check:</p> <ul> <li>Any errors in the startup of von-network?</li> <li>Is the von-network webserver (usually at <code>https:/localhost:9000</code>) accessible? If so, can you click on and see the Genesis File?</li> <li>Do you even need a local ledger? If not, you can use a public sandbox ledger,   such as the BCovrin Test ledger, likely by just prefacing your ACA-Py   command with <code>LEDGER_URL=http://test.bcovrin.vonx.io</code>. For example,   when running the Alice-Faber demo in the demo folder, you can run (for   example), the Faber agent using the command:   <code>LEDGER_URL=http://test.bcovrin.vonx.io ./run_demo faber</code></li> </ul>"},{"location":"testing/Troubleshooting/#any-firewalls","title":"Any Firewalls","text":"<p>Do you have any firewalls in play that might be blocking the ports that are used by the ledger, notably 9701-9708? To access a ledger the ACA-Py instance must be able to get to those ports of the ledger, regardless if the ledger is local or remote.</p>"},{"location":"testing/Troubleshooting/#damaged-unpublishable-revocation-registry","title":"Damaged, Unpublishable Revocation Registry","text":"<p>We have discovered that in the ACA-Py AnonCreds implementation, it is possible to get into a state where the publishing of updates to a Revocation Registry (RevReg) is impossible. This can happen where ACA-Py starts to publish an update to the RevReg, but the write transaction to the Hyperledger Indy ledger fails for some reason. When a credential revocation is published, aca-py (via indy-sdk or askar/credx) updates the revocation state in the wallet as well as on the ledger.  The revocation state is dependant on whatever the previous revocation state is/was, so if the ledger and wallet are mis-matched the publish will fail. (Andrew/s PR # 1804 (merged) should mitigate but probably won't completely eliminate this from happening).</p> <p>For example, in case we've seen, the write RevRegEntry transaction failed at the ledger because there was a problem with accepting the TAA (Transaction Author Agreement). Once the error occurred, the RevReg state held by the ACA-Py agent, and the RevReg state on the ledger were different. Even after the ability to write to the ledger was restored, the RevReg could still not be published because of the differences in the RevReg state. Such a situation can now be corrected, as follows:</p> <p>To address this issue, some new endpoints were added to ACA-Py in Release 0.7.4, as follows:</p> <ul> <li>GET <code>/revocation/registry/&lt;id&gt;/issued</code> - counts of the number of issued/revoked   within a registry</li> <li>GET <code>/revocation/registry/&lt;id&gt;/issued/details</code> - details of all credentials   issued/revoked within a registry</li> <li>GET <code>/revocation/registry/&lt;id&gt;/issued/indy_recs</code> - calculated rev_reg_delta from   the ledger</li> <li>This is used to compare ledger revoked vs wallet revoked credentials, which     is essentially the state of the RevReg on the ledger and in ACA-Py. Where     there is a difference, we have an error.</li> <li>PUT <code>/revocation/registry/&lt;id&gt;/fix-revocation-entry-state</code> - publish an update   to the RevReg state on the ledger to bring it into alignment with what is in   the ACA-Py instance.</li> <li>There is a boolean parameter (<code>apply_ledger_update</code>) to control whether the     ledger entry actually gets published so, if you are so inclined, you can     call the endpoint to see what the transaction would be, before you actually     try to do a ledger update.  This will return:<ul> <li><code>rev_reg_delta</code> - same as the \".../indy_recs\" endpoint</li> <li><code>accum_calculated</code> - transaction to write to ledger</li> <li><code>accum_fixed</code> - If <code>apply_ledger_update</code>, the transaction actually written   to the ledger</li> </ul> </li> </ul> <p>Note that there is (currently) a backlog item to prevent the wallet and ledger from getting out of sync (e.g. don't update the ACA-Py RevReg state if the ledger write fails), but even after that change is made, having this ability will be retained for use if needed.</p> <p>We originally ran into this due to the TAA acceptance getting lost when switching to multi-ledger (as described here. Note that this is one reason how this \"out of sync\" scenario can occur, but there may be others.</p> <p>We add an integration test that demonstrates/tests this issue here.</p> <p>To run the scenario either manually or using the integration tests, you can do the following:</p> <ul> <li>Start von-network in TAA mode:</li> <li><code>./manage start --taa-sample --logs</code></li> <li>Start the tails server as usual:</li> <li><code>./manage start --logs</code></li> <li>To run the scenario manually, start faber and let the agent know it needs to TAA-accept before doing any ledger writes:</li> <li><code>./run_demo faber --revocation --taa-accept</code>, and then you can run through all the transactions using the Swagger page.</li> <li>To run the scenario via an integration test, run:</li> <li><code>./run_bdd -t @taa_required</code></li> </ul>"},{"location":"testing/UnitTests/","title":"ACA-Py Unit Tests","text":"<p>The following covers the Unit Testing framework in ACA-Py, how to run the tests, and how to add unit tests.</p> <p>This video is a presentation of the material covered in this document by developer @shaangill025.</p>"},{"location":"testing/UnitTests/#running-unit-tests-in-aca-py","title":"Running unit tests in ACA-Py","text":"<ul> <li><code>./scripts/run_tests</code></li> <li><code>./scripts/run_tests aries_clouadagent/protocols/out_of_band/v1_0/tests</code></li> <li><code>./scripts/run_tests_indy</code> includes Indy specific tests</li> </ul>"},{"location":"testing/UnitTests/#pytest","title":"Pytest","text":"<p>Example: aries_cloudagent/core/tests/test_event_bus.py</p> <pre><code>@pytest.fixture\ndef event_bus():\n    yield EventBus()\n\n\n@pytest.fixture\ndef profile():\n    yield async_mock.MagicMock()\n\n\n@pytest.fixture\ndef event():\n    event = Event(topic=\"anything\", payload=\"payload\")\n    yield event\n\nclass MockProcessor:\n    def __init__(self):\n        self.profile = None\n        self.event = None\n\n    async def __call__(self, profile, event):\n        self.profile = profile\n        self.event = event\n\n\n@pytest.fixture\ndef processor():\n    yield MockProcessor()\n</code></pre> <pre><code>def test_sub_unsub(event_bus: EventBus, processor):\n    \"\"\"Test subscribe and unsubscribe.\"\"\"\n    event_bus.subscribe(re.compile(\".*\"), processor)\n    assert event_bus.topic_patterns_to_subscribers\n    assert event_bus.topic_patterns_to_subscribers[re.compile(\".*\")] == [processor]\n    event_bus.unsubscribe(re.compile(\".*\"), processor)\n    assert not event_bus.topic_patterns_to_subscribers\n</code></pre> <p>From aries_cloudagent/core/event_bus.py</p> <pre><code>class EventBus:\n    def __init__(self):\n        self.topic_patterns_to_subscribers: Dict[Pattern, List[Callable]] = {}\n\ndef subscribe(self, pattern: Pattern, processor: Callable):\n        if pattern not in self.topic_patterns_to_subscribers:\n            self.topic_patterns_to_subscribers[pattern] = []\n        self.topic_patterns_to_subscribers[pattern].append(processor)\n\ndef unsubscribe(self, pattern: Pattern, processor: Callable):\n    if pattern in self.topic_patterns_to_subscribers:\n        try:\n            index = self.topic_patterns_to_subscribers[pattern].index(processor)\n        except ValueError:\n            return\n        del self.topic_patterns_to_subscribers[pattern][index]\n        if not self.topic_patterns_to_subscribers[pattern]:\n            del self.topic_patterns_to_subscribers[pattern]\n</code></pre> <pre><code>@pytest.mark.asyncio\nasync def test_sub_notify(event_bus: EventBus, profile, event, processor):\n    \"\"\"Test subscriber receives event.\"\"\"\n    event_bus.subscribe(re.compile(\".*\"), processor)\n    await event_bus.notify(profile, event)\n    assert processor.profile == profile\n    assert processor.event == event\n</code></pre> <pre><code>async def notify(self, profile: \"Profile\", event: Event):\n    partials = []\n    for pattern, subscribers in self.topic_patterns_to_subscribers.items():\n        match = pattern.match(event.topic)\n\n        if not match:\n            continue\n\n        for subscriber in subscribers:\n            partials.append(\n                partial(\n                    subscriber,\n                    profile,\n                    event.with_metadata(EventMetadata(pattern, match)),\n                )\n            )\n\n    for processor in partials:\n        try:\n            await processor()\n        except Exception:\n            LOGGER.exception(\"Error occurred while processing event\")\n</code></pre>"},{"location":"testing/UnitTests/#asynctest","title":"asynctest","text":"<p>From: aries_cloudagent/protocols/didexchange/v1_0/tests/test.manager.py</p> <pre><code>class TestDidExchangeManager(AsyncTestCase, TestConfig):\n    async def setUp(self):\n        self.responder = MockResponder()\n\n        self.oob_mock = async_mock.MagicMock(\n            clean_finished_oob_record=async_mock.AsyncMock(return_value=None)\n        )\n\n        self.route_manager = async_mock.MagicMock(RouteManager)\n        ...\n        self.profile = InMemoryProfile.test_profile(\n            {\n                \"default_endpoint\": \"http://aries.ca/endpoint\",\n                \"default_label\": \"This guy\",\n                \"additional_endpoints\": [\"http://aries.ca/another-endpoint\"],\n                \"debug.auto_accept_invites\": True,\n                \"debug.auto_accept_requests\": True,\n                \"multitenant.enabled\": True,\n                \"wallet.id\": True,\n            },\n            bind={\n                BaseResponder: self.responder,\n                OobMessageProcessor: self.oob_mock,\n                RouteManager: self.route_manager,\n                ...\n            },\n        )\n        ...\n\n    async def test_receive_invitation_no_auto_accept(self):\n        async with self.profile.session() as session:\n            mediation_record = MediationRecord(\n                role=MediationRecord.ROLE_CLIENT,\n                state=MediationRecord.STATE_GRANTED,\n                connection_id=self.test_mediator_conn_id,\n                routing_keys=self.test_mediator_routing_keys,\n                endpoint=self.test_mediator_endpoint,\n            )\n            await mediation_record.save(session)\n            with async_mock.patch.object(\n                self.multitenant_mgr, \"get_default_mediator\"\n            ) as mock_get_default_mediator:\n                mock_get_default_mediator.return_value = mediation_record\n                invi_rec = await self.oob_manager.create_invitation(\n                    my_endpoint=\"testendpoint\",\n                    hs_protos=[HSProto.RFC23],\n                )\n\n                invitee_record = await self.manager.receive_invitation(\n                    invi_rec.invitation,\n                    auto_accept=False,\n                )\n                assert invitee_record.state == ConnRecord.State.INVITATION.rfc23\n</code></pre> <pre><code>async def receive_invitation(\n    self,\n    invitation: OOBInvitationMessage,\n    their_public_did: Optional[str] = None,\n    auto_accept: Optional[bool] = None,\n    alias: Optional[str] = None,\n    mediation_id: Optional[str] = None,\n) -&gt; ConnRecord:\n    ...\n    accept = (\n        ConnRecord.ACCEPT_AUTO\n        if (\n            auto_accept\n            or (\n                auto_accept is None\n                and self.profile.settings.get(\"debug.auto_accept_invites\")\n            )\n        )\n        else ConnRecord.ACCEPT_MANUAL\n    )\n    service_item = invitation.services[0]\n    # Create connection record\n    conn_rec = ConnRecord(\n        invitation_key=(\n            DIDKey.from_did(service_item.recipient_keys[0]).public_key_b58\n            if isinstance(service_item, OOBService)\n            else None\n        ),\n        invitation_msg_id=invitation._id,\n        their_label=invitation.label,\n        their_role=ConnRecord.Role.RESPONDER.rfc23,\n        state=ConnRecord.State.INVITATION.rfc23,\n        accept=accept,\n        alias=alias,\n        their_public_did=their_public_did,\n        connection_protocol=DIDX_PROTO,\n    )\n\n    async with self.profile.session() as session:\n        await conn_rec.save(\n            session,\n            reason=\"Created new connection record from invitation\",\n            log_params={\n                \"invitation\": invitation,\n                \"their_role\": ConnRecord.Role.RESPONDER.rfc23,\n            },\n        )\n\n        # Save the invitation for later processing\n        ...\n\n    return conn_rec\n</code></pre>"},{"location":"testing/UnitTests/#other-details","title":"Other details","text":"<ul> <li>Error catching</li> </ul> <pre><code>  with self.assertRaises(DIDXManagerError) as ctx:\n     ...\n  assert \" ... error ...\" in str(ctx.exception)\n</code></pre> <ul> <li> <p>function.<code>assert_called_once_with(parameters)</code>   function.<code>assert_called_once()</code></p> </li> <li> <p>pytest.mark setup in <code>setup.cfg</code>   can be attributed at function or class level. Example, <code>@pytest.mark.indy</code></p> </li> <li> <p>Code coverage   </p> </li> </ul>"}]}
\ No newline at end of file
diff --git a/main/sitemap.xml.gz b/main/sitemap.xml.gz
index 144dcc0a6dd55c9fdd8ec7e9f5dd1395b6968c7f..e87198b59f51a36cad49449bed1fc65982c5a826 100644
GIT binary patch
delta 13
Ucmb=gXP58h;P`Rx`9$^#03%HWjQ{`u

delta 13
Ucmb=gXP58h;4tKRHj%vo02+G(@c;k-